diff --git a/references/posthog-python-references-6.7.10.json b/references/posthog-python-references-6.7.10.json deleted file mode 100644 index 4fde4a5f9..000000000 --- a/references/posthog-python-references-6.7.10.json +++ /dev/null @@ -1,2343 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "6.7.10", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Optional[str]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Optional[str]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "The project API key.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "The host to use for the client.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Whether to enable debug mode.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "any" - }, - { - "name": "uuid", - "description": "A unique identifier for the event.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user by calling decide.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user by calling decide.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user by calling decide.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "dict" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team').", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "End the consumer thread once the queue is empty. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context.", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with posthog.new_context():\n identify_context('')\n posthog.capture('event_name')" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.capture(\n 'event_name',\n distinct_id='user-distinct-id',\n properties={\n '$set': {'name': 'Max Hedgehog'},\n '$set_once': {'initial_url': '/blog'}\n }\n)" - }, - { - "id": "example_2", - "name": "Set using context", - "code": "# Set using context\nfrom posthog import new_context, identify_context\nwith new_context():\n identify_context('user-distinct-id')\n posthog.capture('event_name')" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "any" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()`", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, FeatureFlag]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlag]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled Example: ```python result = posthog.get_feature_flag_result('beta-feature', 'distinct_id') if result and result.enabled: # Use the variant and payload print(f\"Variant: {result.variant}\") print(f\"Payload: {result.payload}\") ```", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group", - "isOptional": true, - "type": "any" - }, - { - "name": "group_key", - "description": "Unique identifier of the group", - "isOptional": true, - "type": "any" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": false, - "type": "any" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Block program until the client clears the queue. Used during program shutdown. You should use `shutdown()` directly in most cases.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context (default: True)", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking (default: True)", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import capture\ncapture(\n 'distinct_id',\n event='event_name',\n properties={\n '$set': {'name': 'Max Hedgehog'},\n '$set_once': {'initial_url': '/blog'}\n }\n)" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import capture\ncapture(\n 'distinct_id',\n event='event_name',\n properties={\n '$set': {'name': 'Max Hedgehog'},\n '$set_once': {'initial_url': '/blog'}\n }\n)" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-6.7.11.json b/references/posthog-python-references-6.7.11.json deleted file mode 100644 index 0ac5a7dc0..000000000 --- a/references/posthog-python-references-6.7.11.json +++ /dev/null @@ -1,2343 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "6.7.11", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Optional[str]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Optional[str]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "The project API key.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "The host to use for the client.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Whether to enable debug mode.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "any" - }, - { - "name": "uuid", - "description": "A unique identifier for the event.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user by calling decide.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user by calling decide.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user by calling decide.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "dict" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team').", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "End the consumer thread once the queue is empty. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context.", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with posthog.new_context():\n identify_context('')\n posthog.capture('event_name')" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.capture(\n 'event_name',\n distinct_id='user-distinct-id',\n properties={\n '$set': {'name': 'Max Hedgehog'},\n '$set_once': {'initial_url': '/blog'}\n }\n)" - }, - { - "id": "example_2", - "name": "Set using context", - "code": "# Set using context\nfrom posthog import new_context, identify_context\nwith new_context():\n identify_context('user-distinct-id')\n posthog.capture('event_name')" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "any" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()`", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, FeatureFlag]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlag]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled Example: ```python result = posthog.get_feature_flag_result('beta-feature', 'distinct_id') if result and result.enabled: # Use the variant and payload print(f\"Variant: {result.variant}\") print(f\"Payload: {result.payload}\") ```", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group", - "isOptional": true, - "type": "any" - }, - { - "name": "group_key", - "description": "Unique identifier of the group", - "isOptional": true, - "type": "any" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": false, - "type": "any" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Block program until the client clears the queue. Used during program shutdown. You should use `shutdown()` directly in most cases.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context (default: True)", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking (default: True)", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import capture\ncapture(\n 'distinct_id',\n event='event_name',\n properties={\n '$set': {'name': 'Max Hedgehog'},\n '$set_once': {'initial_url': '/blog'}\n }\n)" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import capture\ncapture(\n 'distinct_id',\n event='event_name',\n properties={\n '$set': {'name': 'Max Hedgehog'},\n '$set_once': {'initial_url': '/blog'}\n }\n)" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-6.7.12.json b/references/posthog-python-references-6.7.12.json deleted file mode 100644 index c4769c2eb..000000000 --- a/references/posthog-python-references-6.7.12.json +++ /dev/null @@ -1,2343 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "6.7.12", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Optional[str]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Optional[str]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "The project API key.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "The host to use for the client.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Whether to enable debug mode.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "any" - }, - { - "name": "uuid", - "description": "A unique identifier for the event.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user by calling decide.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user by calling decide.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user by calling decide.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "dict" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team').", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "End the consumer thread once the queue is empty. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context.", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with posthog.new_context():\n identify_context('')\n posthog.capture('event_name')" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.capture(\n 'event_name',\n distinct_id='user-distinct-id',\n properties={\n '$set': {'name': 'Max Hedgehog'},\n '$set_once': {'initial_url': '/blog'}\n }\n)" - }, - { - "id": "example_2", - "name": "Set using context", - "code": "# Set using context\nfrom posthog import new_context, identify_context\nwith new_context():\n identify_context('user-distinct-id')\n posthog.capture('event_name')" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "any" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()`", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, FeatureFlag]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlag]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled Example: ```python result = posthog.get_feature_flag_result('beta-feature', 'distinct_id') if result and result.enabled: # Use the variant and payload print(f\"Variant: {result.variant}\") print(f\"Payload: {result.payload}\") ```", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group", - "isOptional": true, - "type": "any" - }, - { - "name": "group_key", - "description": "Unique identifier of the group", - "isOptional": true, - "type": "any" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": false, - "type": "any" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Block program until the client clears the queue. Used during program shutdown. You should use `shutdown()` directly in most cases.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context (default: True)", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking (default: True)", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import capture\ncapture(\n 'distinct_id',\n event='event_name',\n properties={\n '$set': {'name': 'Max Hedgehog'},\n '$set_once': {'initial_url': '/blog'}\n }\n)" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import capture\ncapture(\n 'distinct_id',\n event='event_name',\n properties={\n '$set': {'name': 'Max Hedgehog'},\n '$set_once': {'initial_url': '/blog'}\n }\n)" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-6.7.13.json b/references/posthog-python-references-6.7.13.json deleted file mode 100644 index 6b0c973bf..000000000 --- a/references/posthog-python-references-6.7.13.json +++ /dev/null @@ -1,2343 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "6.7.13", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Optional[str]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Optional[str]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "The project API key.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "The host to use for the client.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Whether to enable debug mode.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "any" - }, - { - "name": "uuid", - "description": "A unique identifier for the event.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user by calling decide.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user by calling decide.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user by calling decide.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "dict" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team').", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "End the consumer thread once the queue is empty. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context.", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with posthog.new_context():\n identify_context('')\n posthog.capture('event_name')" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.capture(\n 'event_name',\n distinct_id='user-distinct-id',\n properties={\n '$set': {'name': 'Max Hedgehog'},\n '$set_once': {'initial_url': '/blog'}\n }\n)" - }, - { - "id": "example_2", - "name": "Set using context", - "code": "# Set using context\nfrom posthog import new_context, identify_context\nwith new_context():\n identify_context('user-distinct-id')\n posthog.capture('event_name')" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "any" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()`", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, FeatureFlag]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlag]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled Example: ```python result = posthog.get_feature_flag_result('beta-feature', 'distinct_id') if result and result.enabled: # Use the variant and payload print(f\"Variant: {result.variant}\") print(f\"Payload: {result.payload}\") ```", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group", - "isOptional": true, - "type": "any" - }, - { - "name": "group_key", - "description": "Unique identifier of the group", - "isOptional": true, - "type": "any" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": false, - "type": "any" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Block program until the client clears the queue. Used during program shutdown. You should use `shutdown()` directly in most cases.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context (default: True)", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking (default: True)", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import capture\ncapture(\n 'distinct_id',\n event='event_name',\n properties={\n '$set': {'name': 'Max Hedgehog'},\n '$set_once': {'initial_url': '/blog'}\n }\n)" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import capture\ncapture(\n 'distinct_id',\n event='event_name',\n properties={\n '$set': {'name': 'Max Hedgehog'},\n '$set_once': {'initial_url': '/blog'}\n }\n)" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-6.7.7.json b/references/posthog-python-references-6.7.7.json deleted file mode 100644 index 3c24b7463..000000000 --- a/references/posthog-python-references-6.7.7.json +++ /dev/null @@ -1,2343 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "6.7.7", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Optional[str]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Optional[str]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "The project API key.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "The host to use for the client.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Whether to enable debug mode.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "any" - }, - { - "name": "uuid", - "description": "A unique identifier for the event.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user by calling decide.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user by calling decide.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user by calling decide.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "dict" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team').", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "End the consumer thread once the queue is empty. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context.", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with posthog.new_context():\n identify_context('')\n posthog.capture('event_name')" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.capture(\n 'event_name',\n distinct_id='user-distinct-id',\n properties={\n '$set': {'name': 'Max Hedgehog'},\n '$set_once': {'initial_url': '/blog'}\n }\n)" - }, - { - "id": "example_2", - "name": "Set using context", - "code": "# Set using context\nfrom posthog import new_context, identify_context\nwith new_context():\n identify_context('user-distinct-id')\n posthog.capture('event_name')" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "any" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()`", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, FeatureFlag]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlag]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled Example: ```python result = posthog.get_feature_flag_result('beta-feature', 'distinct_id') if result and result.enabled: # Use the variant and payload print(f\"Variant: {result.variant}\") print(f\"Payload: {result.payload}\") ```", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group", - "isOptional": true, - "type": "any" - }, - { - "name": "group_key", - "description": "Unique identifier of the group", - "isOptional": true, - "type": "any" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": false, - "type": "any" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Block program until the client clears the queue. Used during program shutdown. You should use `shutdown()` directly in most cases.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context (default: True)", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking (default: True)", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import capture\ncapture(\n 'distinct_id',\n event='event_name',\n properties={\n '$set': {'name': 'Max Hedgehog'},\n '$set_once': {'initial_url': '/blog'}\n }\n)" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import capture\ncapture(\n 'distinct_id',\n event='event_name',\n properties={\n '$set': {'name': 'Max Hedgehog'},\n '$set_once': {'initial_url': '/blog'}\n }\n)" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-6.8.0.json b/references/posthog-python-references-6.8.0.json deleted file mode 100644 index 57c9ab156..000000000 --- a/references/posthog-python-references-6.8.0.json +++ /dev/null @@ -1,2343 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "6.8.0", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Optional[str]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Optional[str]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "The project API key.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "The host to use for the client.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Whether to enable debug mode.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "any" - }, - { - "name": "uuid", - "description": "A unique identifier for the event.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user by calling decide.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user by calling decide.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user by calling decide.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "dict" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team').", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "End the consumer thread once the queue is empty. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context.", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with posthog.new_context():\n identify_context('')\n posthog.capture('event_name')" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.capture(\n 'event_name',\n distinct_id='user-distinct-id',\n properties={\n '$set': {'name': 'Max Hedgehog'},\n '$set_once': {'initial_url': '/blog'}\n }\n)" - }, - { - "id": "example_2", - "name": "Set using context", - "code": "# Set using context\nfrom posthog import new_context, identify_context\nwith new_context():\n identify_context('user-distinct-id')\n posthog.capture('event_name')" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "any" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()`", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, FeatureFlag]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlag]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled Example: ```python result = posthog.get_feature_flag_result('beta-feature', 'distinct_id') if result and result.enabled: # Use the variant and payload print(f\"Variant: {result.variant}\") print(f\"Payload: {result.payload}\") ```", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group", - "isOptional": true, - "type": "any" - }, - { - "name": "group_key", - "description": "Unique identifier of the group", - "isOptional": true, - "type": "any" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": false, - "type": "any" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Block program until the client clears the queue. Used during program shutdown. You should use `shutdown()` directly in most cases.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context (default: True)", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking (default: True)", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import capture\ncapture(\n 'distinct_id',\n event='event_name',\n properties={\n '$set': {'name': 'Max Hedgehog'},\n '$set_once': {'initial_url': '/blog'}\n }\n)" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import capture\ncapture(\n 'distinct_id',\n event='event_name',\n properties={\n '$set': {'name': 'Max Hedgehog'},\n '$set_once': {'initial_url': '/blog'}\n }\n)" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-6.9.0.json b/references/posthog-python-references-6.9.0.json deleted file mode 100644 index 2b534b2d4..000000000 --- a/references/posthog-python-references-6.9.0.json +++ /dev/null @@ -1,2430 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "6.9.0", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Optional[str]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Optional[str]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "The project API key.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "The host to use for the client.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Whether to enable debug mode.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exception_code_variables", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "any" - }, - { - "name": "uuid", - "description": "A unique identifier for the event.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user by calling decide.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user by calling decide.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user by calling decide.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "dict" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team').", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "End the consumer thread once the queue is empty. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context.", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with posthog.new_context():\n identify_context('')\n posthog.capture('event_name')" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.capture(\n 'event_name',\n distinct_id='user-distinct-id',\n properties={\n '$set': {'name': 'Max Hedgehog'},\n '$set_once': {'initial_url': '/blog'}\n }\n)" - }, - { - "id": "example_2", - "name": "Set using context", - "code": "# Set using context\nfrom posthog import new_context, identify_context\nwith new_context():\n identify_context('user-distinct-id')\n posthog.capture('event_name')" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "any" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()`", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, FeatureFlag]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlag]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled Example: ```python result = posthog.get_feature_flag_result('beta-feature', 'distinct_id') if result and result.enabled: # Use the variant and payload print(f\"Variant: {result.variant}\") print(f\"Payload: {result.payload}\") ```", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group", - "isOptional": true, - "type": "any" - }, - { - "name": "group_key", - "description": "Unique identifier of the group", - "isOptional": true, - "type": "any" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": false, - "type": "any" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Block program until the client clears the queue. Used during program shutdown. You should use `shutdown()` directly in most cases.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context (default: True)", - "isOptional": false, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking (default: True)", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import capture\ncapture(\n 'distinct_id',\n event='event_name',\n properties={\n '$set': {'name': 'Max Hedgehog'},\n '$set_once': {'initial_url': '/blog'}\n }\n)" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Set whether code variables are captured for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Variable names matching these patterns will be ignored completely when capturing code variables.", - "details": "", - "category": null, - "params": [ - { - "name": "ignore_patterns", - "description": "", - "isOptional": true, - "type": "list" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Variable names matching these patterns will be masked with *** when capturing code variables.", - "details": "", - "category": null, - "params": [ - { - "name": "mask_patterns", - "description": "", - "isOptional": true, - "type": "list" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import capture\ncapture(\n 'distinct_id',\n event='event_name',\n properties={\n '$set': {'name': 'Max Hedgehog'},\n '$set_once': {'initial_url': '/blog'}\n }\n)" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-6.9.1.json b/references/posthog-python-references-6.9.1.json deleted file mode 100644 index eb26f3aec..000000000 --- a/references/posthog-python-references-6.9.1.json +++ /dev/null @@ -1,2425 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "6.9.1", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Optional[str]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Optional[str]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "The project API key.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "The host to use for the client.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Whether to enable debug mode.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exception_code_variables", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "any" - }, - { - "name": "uuid", - "description": "A unique identifier for the event.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user by calling decide.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user by calling decide.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user by calling decide.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "dict" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team').", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "End the consumer thread once the queue is empty. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context.", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with posthog.new_context():\n identify_context('')\n posthog.capture('event_name')" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "any" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()`", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, FeatureFlag]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlag]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled Example: ```python result = posthog.get_feature_flag_result('beta-feature', 'distinct_id') if result and result.enabled: # Use the variant and payload print(f\"Variant: {result.variant}\") print(f\"Payload: {result.payload}\") ```", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group", - "isOptional": true, - "type": "any" - }, - { - "name": "group_key", - "description": "Unique identifier of the group", - "isOptional": true, - "type": "any" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": false, - "type": "any" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Block program until the client clears the queue. Used during program shutdown. You should use `shutdown()` directly in most cases.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context (default: True)", - "isOptional": false, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking (default: True)", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import capture\ncapture(\n 'distinct_id',\n event='event_name',\n properties={\n '$set': {'name': 'Max Hedgehog'},\n '$set_once': {'initial_url': '/blog'}\n }\n)" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Set whether code variables are captured for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Variable names matching these patterns will be ignored completely when capturing code variables.", - "details": "", - "category": null, - "params": [ - { - "name": "ignore_patterns", - "description": "", - "isOptional": true, - "type": "list" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Variable names matching these patterns will be masked with *** when capturing code variables.", - "details": "", - "category": null, - "params": [ - { - "name": "mask_patterns", - "description": "", - "isOptional": true, - "type": "list" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import capture\ncapture(\n 'distinct_id',\n event='event_name',\n properties={\n '$set': {'name': 'Max Hedgehog'},\n '$set_once': {'initial_url': '/blog'}\n }\n)" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-6.9.2.json b/references/posthog-python-references-6.9.2.json deleted file mode 100644 index f1a1625d6..000000000 --- a/references/posthog-python-references-6.9.2.json +++ /dev/null @@ -1,2425 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "6.9.2", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Optional[str]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Optional[str]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "The project API key.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "The host to use for the client.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Whether to enable debug mode.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exception_code_variables", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "any" - }, - { - "name": "uuid", - "description": "A unique identifier for the event.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user by calling decide.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user by calling decide.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user by calling decide.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "dict" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team').", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "End the consumer thread once the queue is empty. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context.", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with posthog.new_context():\n identify_context('')\n posthog.capture('event_name')" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "any" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()`", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, FeatureFlag]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlag]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled Example: ```python result = posthog.get_feature_flag_result('beta-feature', 'distinct_id') if result and result.enabled: # Use the variant and payload print(f\"Variant: {result.variant}\") print(f\"Payload: {result.payload}\") ```", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group", - "isOptional": true, - "type": "any" - }, - { - "name": "group_key", - "description": "Unique identifier of the group", - "isOptional": true, - "type": "any" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": false, - "type": "any" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Block program until the client clears the queue. Used during program shutdown. You should use `shutdown()` directly in most cases.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context (default: True)", - "isOptional": false, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking (default: True)", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import capture\ncapture(\n 'distinct_id',\n event='event_name',\n properties={\n '$set': {'name': 'Max Hedgehog'},\n '$set_once': {'initial_url': '/blog'}\n }\n)" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Set whether code variables are captured for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Variable names matching these patterns will be ignored completely when capturing code variables.", - "details": "", - "category": null, - "params": [ - { - "name": "ignore_patterns", - "description": "", - "isOptional": true, - "type": "list" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Variable names matching these patterns will be masked with *** when capturing code variables.", - "details": "", - "category": null, - "params": [ - { - "name": "mask_patterns", - "description": "", - "isOptional": true, - "type": "list" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import capture\ncapture(\n 'distinct_id',\n event='event_name',\n properties={\n '$set': {'name': 'Max Hedgehog'},\n '$set_once': {'initial_url': '/blog'}\n }\n)" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.0.0.json b/references/posthog-python-references-7.0.0.json deleted file mode 100644 index 53d2ccdb2..000000000 --- a/references/posthog-python-references-7.0.0.json +++ /dev/null @@ -1,2425 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.0.0", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Optional[str]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Optional[str]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "The project API key.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "The host to use for the client.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Whether to enable debug mode.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exception_code_variables", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "any" - }, - { - "name": "uuid", - "description": "A unique identifier for the event.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user by calling decide.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user by calling decide.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user by calling decide.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "dict" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team').", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "End the consumer thread once the queue is empty. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context.", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with posthog.new_context():\n identify_context('')\n posthog.capture('event_name')" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "any" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()`", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, FeatureFlag]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlag]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled Example: ```python result = posthog.get_feature_flag_result('beta-feature', 'distinct_id') if result and result.enabled: # Use the variant and payload print(f\"Variant: {result.variant}\") print(f\"Payload: {result.payload}\") ```", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group", - "isOptional": true, - "type": "any" - }, - { - "name": "group_key", - "description": "Unique identifier of the group", - "isOptional": true, - "type": "any" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": false, - "type": "any" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Block program until the client clears the queue. Used during program shutdown. You should use `shutdown()` directly in most cases.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context (default: True)", - "isOptional": false, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking (default: True)", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import capture\ncapture(\n 'distinct_id',\n event='event_name',\n properties={\n '$set': {'name': 'Max Hedgehog'},\n '$set_once': {'initial_url': '/blog'}\n }\n)" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Set whether code variables are captured for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Variable names matching these patterns will be ignored completely when capturing code variables.", - "details": "", - "category": null, - "params": [ - { - "name": "ignore_patterns", - "description": "", - "isOptional": true, - "type": "list" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Variable names matching these patterns will be masked with *** when capturing code variables.", - "details": "", - "category": null, - "params": [ - { - "name": "mask_patterns", - "description": "", - "isOptional": true, - "type": "list" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import capture\ncapture(\n 'distinct_id',\n event='event_name',\n properties={\n '$set': {'name': 'Max Hedgehog'},\n '$set_once': {'initial_url': '/blog'}\n }\n)" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.0.1.json b/references/posthog-python-references-7.0.1.json deleted file mode 100644 index fc608f585..000000000 --- a/references/posthog-python-references-7.0.1.json +++ /dev/null @@ -1,2425 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.0.1", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Optional[str]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Optional[str]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "The project API key.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "The host to use for the client.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Whether to enable debug mode.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exception_code_variables", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "any" - }, - { - "name": "uuid", - "description": "A unique identifier for the event.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user by calling decide.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user by calling decide.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user by calling decide.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "dict" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team').", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "End the consumer thread once the queue is empty. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context.", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with posthog.new_context():\n identify_context('')\n posthog.capture('event_name')" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "any" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()`", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, FeatureFlag]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlag]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled Example: ```python result = posthog.get_feature_flag_result('beta-feature', 'distinct_id') if result and result.enabled: # Use the variant and payload print(f\"Variant: {result.variant}\") print(f\"Payload: {result.payload}\") ```", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group", - "isOptional": true, - "type": "any" - }, - { - "name": "group_key", - "description": "Unique identifier of the group", - "isOptional": true, - "type": "any" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": false, - "type": "any" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Block program until the client clears the queue. Used during program shutdown. You should use `shutdown()` directly in most cases.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context (default: True)", - "isOptional": false, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking (default: True)", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import capture\ncapture(\n 'distinct_id',\n event='event_name',\n properties={\n '$set': {'name': 'Max Hedgehog'},\n '$set_once': {'initial_url': '/blog'}\n }\n)" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Set whether code variables are captured for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Variable names matching these patterns will be ignored completely when capturing code variables.", - "details": "", - "category": null, - "params": [ - { - "name": "ignore_patterns", - "description": "", - "isOptional": true, - "type": "list" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Variable names matching these patterns will be masked with *** when capturing code variables.", - "details": "", - "category": null, - "params": [ - { - "name": "mask_patterns", - "description": "", - "isOptional": true, - "type": "list" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import capture\ncapture(\n 'distinct_id',\n event='event_name',\n properties={\n '$set': {'name': 'Max Hedgehog'},\n '$set_once': {'initial_url': '/blog'}\n }\n)" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.14.0.json b/references/posthog-python-references-7.14.0.json deleted file mode 100644 index 955b57dd4..000000000 --- a/references/posthog-python-references-7.14.0.json +++ /dev/null @@ -1,2725 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.14.0", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Optional[str]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Optional[str]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "The project API key.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "The host to use for the client.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Whether to enable debug mode.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "", - "isOptional": false, - "type": "UnionType[list[str], any]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "any" - }, - { - "name": "uuid", - "description": "A unique identifier for the event.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "dict[str, str]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys to scope the underlying ``/flags`` request to a subset.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "dict" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team').", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "End the consumer thread once the queue is empty. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context.", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with posthog.new_context():\n identify_context('')\n posthog.capture('event_name')" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "any" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()`", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "any" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys. When provided, only these flags are evaluated \u2014 the underlying ``/flags`` request asks the server for just this subset, which makes the response smaller and the request cheaper. Use this when you only need a handful of flags out of many.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, FeatureFlag]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlag]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled Example: ```python result = posthog.get_feature_flag_result('beta-feature', 'distinct_id') if result and result.enabled: # Use the variant and payload print(f\"Variant: {result.variant}\") print(f\"Payload: {result.payload}\") ```", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group", - "isOptional": true, - "type": "any" - }, - { - "name": "group_key", - "description": "Unique identifier of the group", - "isOptional": true, - "type": "any" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": false, - "type": "any" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Block program until the client clears the queue. Used during program shutdown. You should use `shutdown()` directly in most cases.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context (default: True)", - "isOptional": false, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking (default: True)", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import capture\ncapture(\n 'distinct_id',\n event='event_name',\n properties={\n '$set': {'name': 'Max Hedgehog'},\n '$set_once': {'initial_url': '/blog'}\n }\n)" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Set whether code variables are captured for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Variable names matching these patterns will be ignored completely when capturing code variables.", - "details": "", - "category": null, - "params": [ - { - "name": "ignore_patterns", - "description": "", - "isOptional": true, - "type": "list" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Variable names matching these patterns will be masked with *** when capturing code variables.", - "details": "", - "category": null, - "params": [ - { - "name": "mask_patterns", - "description": "", - "isOptional": true, - "type": "list" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import capture\ncapture(\n 'distinct_id',\n event='event_name',\n properties={\n '$set': {'name': 'Max Hedgehog'},\n '$set_once': {'initial_url': '/blog'}\n }\n)" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.14.1.json b/references/posthog-python-references-7.14.1.json deleted file mode 100644 index 2dd4000c1..000000000 --- a/references/posthog-python-references-7.14.1.json +++ /dev/null @@ -1,2725 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.14.1", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Optional[str]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Optional[str]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "The project API key.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "The host to use for the client.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Whether to enable debug mode.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "", - "isOptional": false, - "type": "UnionType[list[str], any]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "any" - }, - { - "name": "uuid", - "description": "A unique identifier for the event.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "dict[str, str]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys to scope the underlying ``/flags`` request to a subset.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "dict" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team').", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "End the consumer thread once the queue is empty. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context.", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with posthog.new_context():\n identify_context('')\n posthog.capture('event_name')" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "any" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()`", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "any" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys. When provided, only these flags are evaluated \u2014 the underlying ``/flags`` request asks the server for just this subset, which makes the response smaller and the request cheaper. Use this when you only need a handful of flags out of many.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, FeatureFlag]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlag]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled Example: ```python result = posthog.get_feature_flag_result('beta-feature', 'distinct_id') if result and result.enabled: # Use the variant and payload print(f\"Variant: {result.variant}\") print(f\"Payload: {result.payload}\") ```", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group", - "isOptional": true, - "type": "any" - }, - { - "name": "group_key", - "description": "Unique identifier of the group", - "isOptional": true, - "type": "any" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": false, - "type": "any" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Block program until the client clears the queue. Used during program shutdown. You should use `shutdown()` directly in most cases.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context (default: True)", - "isOptional": false, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking (default: True)", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import capture\ncapture(\n 'distinct_id',\n event='event_name',\n properties={\n '$set': {'name': 'Max Hedgehog'},\n '$set_once': {'initial_url': '/blog'}\n }\n)" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Set whether code variables are captured for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Variable names matching these patterns will be ignored completely when capturing code variables.", - "details": "", - "category": null, - "params": [ - { - "name": "ignore_patterns", - "description": "", - "isOptional": true, - "type": "list" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Variable names matching these patterns will be masked with *** when capturing code variables.", - "details": "", - "category": null, - "params": [ - { - "name": "mask_patterns", - "description": "", - "isOptional": true, - "type": "list" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import capture\ncapture(\n 'distinct_id',\n event='event_name',\n properties={\n '$set': {'name': 'Max Hedgehog'},\n '$set_once': {'initial_url': '/blog'}\n }\n)" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.15.0.json b/references/posthog-python-references-7.15.0.json deleted file mode 100644 index 988ba4105..000000000 --- a/references/posthog-python-references-7.15.0.json +++ /dev/null @@ -1,2725 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.15.0", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Optional[str]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Optional[str]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "The project API key.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "The host to use for the client.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Whether to enable debug mode.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "", - "isOptional": false, - "type": "UnionType[list[str], any]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "any" - }, - { - "name": "uuid", - "description": "A unique identifier for the event.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "dict[str, str]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys to scope the underlying ``/flags`` request to a subset.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "dict" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team').", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "End the consumer thread once the queue is empty. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context.", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with posthog.new_context():\n identify_context('')\n posthog.capture('event_name')" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "any" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()`", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "any" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys. When provided, only these flags are evaluated \u2014 the underlying ``/flags`` request asks the server for just this subset, which makes the response smaller and the request cheaper. Use this when you only need a handful of flags out of many.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, FeatureFlag]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlag]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled Example: ```python result = posthog.get_feature_flag_result('beta-feature', 'distinct_id') if result and result.enabled: # Use the variant and payload print(f\"Variant: {result.variant}\") print(f\"Payload: {result.payload}\") ```", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group", - "isOptional": true, - "type": "any" - }, - { - "name": "group_key", - "description": "Unique identifier of the group", - "isOptional": true, - "type": "any" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": false, - "type": "any" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Block program until the client clears the queue. Used during program shutdown. You should use `shutdown()` directly in most cases.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context (default: True)", - "isOptional": false, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking (default: True)", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import capture\ncapture(\n 'distinct_id',\n event='event_name',\n properties={\n '$set': {'name': 'Max Hedgehog'},\n '$set_once': {'initial_url': '/blog'}\n }\n)" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Set whether code variables are captured for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Variable names matching these patterns will be ignored completely when capturing code variables.", - "details": "", - "category": null, - "params": [ - { - "name": "ignore_patterns", - "description": "", - "isOptional": true, - "type": "list" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Variable names matching these patterns will be masked with *** when capturing code variables.", - "details": "", - "category": null, - "params": [ - { - "name": "mask_patterns", - "description": "", - "isOptional": true, - "type": "list" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import capture\ncapture(\n 'distinct_id',\n event='event_name',\n properties={\n '$set': {'name': 'Max Hedgehog'},\n '$set_once': {'initial_url': '/blog'}\n }\n)" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.15.1.json b/references/posthog-python-references-7.15.1.json deleted file mode 100644 index 0977aaa79..000000000 --- a/references/posthog-python-references-7.15.1.json +++ /dev/null @@ -1,2912 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.15.1", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Optional[str]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Optional[str]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "Optional callback invoked by background consumers when an upload fails.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries for background consumers.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "If True, send each event synchronously instead of using background worker threads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Personal API key used for local feature flag evaluation and remote config payloads.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "any" - }, - { - "name": "uuid", - "description": "A unique identifier for the event.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "dict[str, str]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys to scope the underlying ``/flags`` request to a subset.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "dict" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team').", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "End the consumer thread once the queue is empty. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context.", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with posthog.new_context():\n identify_context('')\n posthog.capture('event_name')" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "any" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "any" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys. When provided, only these flags are evaluated \u2014 the underlying ``/flags`` request asks the server for just this subset, which makes the response smaller and the request cheaper. Use this when you only need a handful of flags out of many.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, FeatureFlag]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlag]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "any" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "any" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group", - "isOptional": true, - "type": "any" - }, - { - "name": "group_key", - "description": "Unique identifier of the group", - "isOptional": true, - "type": "any" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": false, - "type": "any" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Block program until the client clears the queue. Used during program shutdown. You should use `shutdown()` directly in most cases.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context (default: True)", - "isOptional": false, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking (default: True)", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. Raises: ValueError: If ``api_key`` has not been configured.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.15.3.json b/references/posthog-python-references-7.15.3.json deleted file mode 100644 index e75be17ec..000000000 --- a/references/posthog-python-references-7.15.3.json +++ /dev/null @@ -1,2912 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.15.3", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Optional[str]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Optional[str]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "Optional callback invoked by background consumers when an upload fails.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries for background consumers.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "If True, send each event synchronously instead of using background worker threads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Personal API key used for local feature flag evaluation and remote config payloads.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "any" - }, - { - "name": "uuid", - "description": "A unique identifier for the event.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "dict[str, str]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys to scope the underlying ``/flags`` request to a subset.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "dict" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team').", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "End the consumer thread once the queue is empty. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context.", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with posthog.new_context():\n identify_context('')\n posthog.capture('event_name')" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "any" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "any" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys. When provided, only these flags are evaluated \u2014 the underlying ``/flags`` request asks the server for just this subset, which makes the response smaller and the request cheaper. Use this when you only need a handful of flags out of many.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, FeatureFlag]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlag]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "any" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "any" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group", - "isOptional": true, - "type": "any" - }, - { - "name": "group_key", - "description": "Unique identifier of the group", - "isOptional": true, - "type": "any" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": false, - "type": "any" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Block program until the client clears the queue. Used during program shutdown. You should use `shutdown()` directly in most cases.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context (default: True)", - "isOptional": false, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking (default: True)", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. Raises: ValueError: If ``api_key`` has not been configured.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.15.4.json b/references/posthog-python-references-7.15.4.json deleted file mode 100644 index a659d92e1..000000000 --- a/references/posthog-python-references-7.15.4.json +++ /dev/null @@ -1,2912 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.15.4", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Optional[str]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Optional[str]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "Optional callback invoked by background consumers when an upload fails.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries for background consumers.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "If True, send each event synchronously instead of using background worker threads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Personal API key used for local feature flag evaluation and remote config payloads.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "any" - }, - { - "name": "uuid", - "description": "A unique identifier for the event.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "dict[str, str]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys to scope the underlying ``/flags`` request to a subset.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "dict" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team').", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "End the consumer thread once the queue is empty. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context.", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with posthog.new_context():\n identify_context('')\n posthog.capture('event_name')" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "any" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "any" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys. When provided, only these flags are evaluated \u2014 the underlying ``/flags`` request asks the server for just this subset, which makes the response smaller and the request cheaper. Use this when you only need a handful of flags out of many.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, FeatureFlag]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlag]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "any" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "any" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group", - "isOptional": true, - "type": "any" - }, - { - "name": "group_key", - "description": "Unique identifier of the group", - "isOptional": true, - "type": "any" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": false, - "type": "any" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Block program until the client clears the queue. Used during program shutdown. You should use `shutdown()` directly in most cases.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context (default: True)", - "isOptional": false, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking (default: True)", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. Raises: ValueError: If ``api_key`` has not been configured.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.16.0.json b/references/posthog-python-references-7.16.0.json deleted file mode 100644 index b56a23512..000000000 --- a/references/posthog-python-references-7.16.0.json +++ /dev/null @@ -1,2912 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.16.0", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Optional[str]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Optional[str]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "Optional callback invoked by background consumers when an upload fails.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries for background consumers.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "If True, send each event synchronously instead of using background worker threads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Personal API key used for local feature flag evaluation and remote config payloads.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "any" - }, - { - "name": "uuid", - "description": "A unique identifier for the event.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "dict[str, str]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys to scope the underlying ``/flags`` request to a subset.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "dict" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team').", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "End the consumer thread once the queue is empty. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context.", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with posthog.new_context():\n identify_context('')\n posthog.capture('event_name')" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "any" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "any" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys. When provided, only these flags are evaluated \u2014 the underlying ``/flags`` request asks the server for just this subset, which makes the response smaller and the request cheaper. Use this when you only need a handful of flags out of many.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, FeatureFlag]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlag]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "any" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "any" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group", - "isOptional": true, - "type": "any" - }, - { - "name": "group_key", - "description": "Unique identifier of the group", - "isOptional": true, - "type": "any" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": false, - "type": "any" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Block program until the client clears the queue. Used during program shutdown. You should use `shutdown()` directly in most cases.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context (default: True)", - "isOptional": false, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking (default: True)", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. Raises: ValueError: If ``api_key`` has not been configured.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.16.1.json b/references/posthog-python-references-7.16.1.json deleted file mode 100644 index 62220ced4..000000000 --- a/references/posthog-python-references-7.16.1.json +++ /dev/null @@ -1,2912 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.16.1", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Optional[str]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Optional[str]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "Optional callback invoked by background consumers when an upload fails.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries for background consumers.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "If True, send each event synchronously instead of using background worker threads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Personal API key used for local feature flag evaluation and remote config payloads.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "any" - }, - { - "name": "uuid", - "description": "A unique identifier for the event.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "dict[str, str]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys to scope the underlying ``/flags`` request to a subset.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "dict" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team').", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "End the consumer thread once the queue is empty. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context.", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with posthog.new_context():\n identify_context('')\n posthog.capture('event_name')" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "any" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "any" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys. When provided, only these flags are evaluated \u2014 the underlying ``/flags`` request asks the server for just this subset, which makes the response smaller and the request cheaper. Use this when you only need a handful of flags out of many.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, FeatureFlag]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlag]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "any" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "any" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group", - "isOptional": true, - "type": "any" - }, - { - "name": "group_key", - "description": "Unique identifier of the group", - "isOptional": true, - "type": "any" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": false, - "type": "any" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Block program until the client clears the queue. Used during program shutdown. You should use `shutdown()` directly in most cases.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context (default: True)", - "isOptional": false, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking (default: True)", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. Raises: ValueError: If ``api_key`` has not been configured.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.16.2.json b/references/posthog-python-references-7.16.2.json deleted file mode 100644 index 2fc1c0bbe..000000000 --- a/references/posthog-python-references-7.16.2.json +++ /dev/null @@ -1,2912 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.16.2", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Optional[str]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Optional[str]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "Optional callback invoked by background consumers when an upload fails.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries for background consumers.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "If True, send each event synchronously instead of using background worker threads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Personal API key used for local feature flag evaluation and remote config payloads.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "any" - }, - { - "name": "uuid", - "description": "A unique identifier for the event.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "dict[str, str]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys to scope the underlying ``/flags`` request to a subset.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "dict" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team').", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "End the consumer thread once the queue is empty. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context.", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with posthog.new_context():\n identify_context('')\n posthog.capture('event_name')" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "any" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "any" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys. When provided, only these flags are evaluated \u2014 the underlying ``/flags`` request asks the server for just this subset, which makes the response smaller and the request cheaper. Use this when you only need a handful of flags out of many.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, FeatureFlag]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlag]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "any" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "any" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group", - "isOptional": true, - "type": "any" - }, - { - "name": "group_key", - "description": "Unique identifier of the group", - "isOptional": true, - "type": "any" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": false, - "type": "any" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Block program until the client clears the queue. Used during program shutdown. You should use `shutdown()` directly in most cases.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context (default: True)", - "isOptional": false, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking (default: True)", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If ``api_key`` is missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.16.3.json b/references/posthog-python-references-7.16.3.json deleted file mode 100644 index 48408c622..000000000 --- a/references/posthog-python-references-7.16.3.json +++ /dev/null @@ -1,2912 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.16.3", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Optional[str]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Optional[str]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "Optional callback invoked by background consumers when an upload fails.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries for background consumers.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "If True, send each event synchronously instead of using background worker threads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Personal API key used for local feature flag evaluation and remote config payloads.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "any" - }, - { - "name": "uuid", - "description": "A unique identifier for the event.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "dict[str, str]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys to scope the underlying ``/flags`` request to a subset.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "dict" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team').", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "End the consumer thread once the queue is empty. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context.", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with posthog.new_context():\n identify_context('')\n posthog.capture('event_name')" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "any" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "any" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys. When provided, only these flags are evaluated \u2014 the underlying ``/flags`` request asks the server for just this subset, which makes the response smaller and the request cheaper. Use this when you only need a handful of flags out of many.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, FeatureFlag]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlag]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "any" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "any" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group", - "isOptional": true, - "type": "any" - }, - { - "name": "group_key", - "description": "Unique identifier of the group", - "isOptional": true, - "type": "any" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": false, - "type": "any" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Block program until the client clears the queue. Used during program shutdown. You should use `shutdown()` directly in most cases.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context (default: True)", - "isOptional": false, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking (default: True)", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If ``api_key`` is missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.16.4.json b/references/posthog-python-references-7.16.4.json deleted file mode 100644 index fea4c0708..000000000 --- a/references/posthog-python-references-7.16.4.json +++ /dev/null @@ -1,2912 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.16.4", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Optional[str]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Optional[str]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "Optional callback invoked by background consumers when an upload fails.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries for background consumers.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "If True, send each event synchronously instead of using background worker threads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Personal API key used for local feature flag evaluation and remote config payloads.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "any" - }, - { - "name": "uuid", - "description": "A unique identifier for the event.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "dict[str, str]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys to scope the underlying ``/flags`` request to a subset.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "dict" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team').", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "End the consumer thread once the queue is empty. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context.", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with posthog.new_context():\n identify_context('')\n posthog.capture('event_name')" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "any" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "any" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys. When provided, only these flags are evaluated \u2014 the underlying ``/flags`` request asks the server for just this subset, which makes the response smaller and the request cheaper. Use this when you only need a handful of flags out of many.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, FeatureFlag]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlag]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "any" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "any" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group", - "isOptional": true, - "type": "any" - }, - { - "name": "group_key", - "description": "Unique identifier of the group", - "isOptional": true, - "type": "any" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": false, - "type": "any" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Block program until the client clears the queue. Used during program shutdown. You should use `shutdown()` directly in most cases.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context (default: True)", - "isOptional": false, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking (default: True)", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If ``api_key`` is missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.17.0.json b/references/posthog-python-references-7.17.0.json deleted file mode 100644 index 18b1d67ff..000000000 --- a/references/posthog-python-references-7.17.0.json +++ /dev/null @@ -1,2918 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.17.0", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Optional[str]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Optional[str]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "Optional callback invoked by background consumers when an upload fails.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries for background consumers.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "If True, send each event synchronously instead of using background worker threads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Personal API key used for local feature flag evaluation and remote config payloads.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "any" - }, - { - "name": "uuid", - "description": "A unique identifier for the event.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "dict[str, str]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys to scope the underlying ``/flags`` request to a subset.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "dict" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team').", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "End the consumer thread once the queue is empty. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context.", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with posthog.new_context():\n identify_context('')\n posthog.capture('event_name')" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "any" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "any" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys. When provided, only these flags are evaluated \u2014 the underlying ``/flags`` request asks the server for just this subset, which makes the response smaller and the request cheaper. Use this when you only need a handful of flags out of many.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, FeatureFlag]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlag]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "any" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "any" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group", - "isOptional": true, - "type": "any" - }, - { - "name": "group_key", - "description": "Unique identifier of the group", - "isOptional": true, - "type": "any" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": false, - "type": "any" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Block program until the client clears the queue. Used during program shutdown. You should use `shutdown()` directly in most cases.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context (default: True)", - "isOptional": false, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking (default: True)", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If ``api_key`` is missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.18.0.json b/references/posthog-python-references-7.18.0.json deleted file mode 100644 index 9f690ab24..000000000 --- a/references/posthog-python-references-7.18.0.json +++ /dev/null @@ -1,2918 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.18.0", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Optional[str]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Optional[str]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "Optional callback invoked by background consumers when an upload fails.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries for background consumers.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "If True, send each event synchronously instead of using background worker threads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Personal API key used for local feature flag evaluation and remote config payloads.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "any" - }, - { - "name": "uuid", - "description": "A unique identifier for the event.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "dict[str, str]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys to scope the underlying ``/flags`` request to a subset.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "dict" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team').", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "End the consumer thread once the queue is empty. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context.", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with posthog.new_context():\n identify_context('')\n posthog.capture('event_name')" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "any" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "any" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys. When provided, only these flags are evaluated \u2014 the underlying ``/flags`` request asks the server for just this subset, which makes the response smaller and the request cheaper. Use this when you only need a handful of flags out of many.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, FeatureFlag]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlag]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "any" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "any" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group", - "isOptional": true, - "type": "any" - }, - { - "name": "group_key", - "description": "Unique identifier of the group", - "isOptional": true, - "type": "any" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": false, - "type": "any" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Block program until the client clears the queue. Used during program shutdown. You should use `shutdown()` directly in most cases.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context (default: True)", - "isOptional": false, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking (default: True)", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If ``api_key`` is missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.18.1.json b/references/posthog-python-references-7.18.1.json deleted file mode 100644 index 3e6ffe884..000000000 --- a/references/posthog-python-references-7.18.1.json +++ /dev/null @@ -1,2924 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.18.1", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Optional[str]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Optional[str]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "Optional callback invoked by background consumers when an upload fails.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries for background consumers.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "If True, send each event synchronously instead of using background worker threads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Personal API key used for local feature flag evaluation and remote config payloads.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "_dedicated_ai_endpoint", - "description": "", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "any" - }, - { - "name": "uuid", - "description": "A unique identifier for the event.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "dict[str, str]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys to scope the underlying ``/flags`` request to a subset.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "dict" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team').", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "End the consumer thread once the queue is empty. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context.", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with posthog.new_context():\n identify_context('')\n posthog.capture('event_name')" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "any" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "any" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys. When provided, only these flags are evaluated \u2014 the underlying ``/flags`` request asks the server for just this subset, which makes the response smaller and the request cheaper. Use this when you only need a handful of flags out of many.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, FeatureFlag]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlag]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "any" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "any" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group", - "isOptional": true, - "type": "any" - }, - { - "name": "group_key", - "description": "Unique identifier of the group", - "isOptional": true, - "type": "any" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": false, - "type": "any" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Block program until the client clears the queue. Used during program shutdown. You should use `shutdown()` directly in most cases.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context (default: True)", - "isOptional": false, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking (default: True)", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If ``api_key`` is missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.18.2.json b/references/posthog-python-references-7.18.2.json deleted file mode 100644 index 3f06fd7e3..000000000 --- a/references/posthog-python-references-7.18.2.json +++ /dev/null @@ -1,2924 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.18.2", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Optional[str]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Optional[str]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "Optional callback invoked by background consumers when an upload fails.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries for background consumers.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "If True, send each event synchronously instead of using background worker threads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Personal API key used for local feature flag evaluation and remote config payloads.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "_dedicated_ai_endpoint", - "description": "", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "any" - }, - { - "name": "uuid", - "description": "A unique identifier for the event.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "dict[str, str]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys to scope the underlying ``/flags`` request to a subset.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "dict" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team').", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "End the consumer thread once the queue is empty. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context.", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with posthog.new_context():\n identify_context('')\n posthog.capture('event_name')" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "any" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "any" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys. When provided, only these flags are evaluated \u2014 the underlying ``/flags`` request asks the server for just this subset, which makes the response smaller and the request cheaper. Use this when you only need a handful of flags out of many.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, FeatureFlag]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlag]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "any" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "any" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group", - "isOptional": true, - "type": "any" - }, - { - "name": "group_key", - "description": "Unique identifier of the group", - "isOptional": true, - "type": "any" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": false, - "type": "any" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Block program until the client clears the queue. Used during program shutdown. You should use `shutdown()` directly in most cases.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context (default: True)", - "isOptional": false, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking (default: True)", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If ``api_key`` is missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.18.3.json b/references/posthog-python-references-7.18.3.json deleted file mode 100644 index e3e8c526a..000000000 --- a/references/posthog-python-references-7.18.3.json +++ /dev/null @@ -1,2924 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.18.3", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Optional[str]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Optional[str]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "Optional callback invoked by background consumers when an upload fails.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries for background consumers.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "If True, send each event synchronously instead of using background worker threads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Personal API key used for local feature flag evaluation and remote config payloads.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "_dedicated_ai_endpoint", - "description": "", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "any" - }, - { - "name": "uuid", - "description": "A unique identifier for the event.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "dict[str, str]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys to scope the underlying ``/flags`` request to a subset.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "dict" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team').", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "End the consumer thread once the queue is empty. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context.", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with posthog.new_context():\n identify_context('')\n posthog.capture('event_name')" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "any" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "any" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys. When provided, only these flags are evaluated \u2014 the underlying ``/flags`` request asks the server for just this subset, which makes the response smaller and the request cheaper. Use this when you only need a handful of flags out of many.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, FeatureFlag]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlag]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "any" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "any" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group", - "isOptional": true, - "type": "any" - }, - { - "name": "group_key", - "description": "Unique identifier of the group", - "isOptional": true, - "type": "any" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": false, - "type": "any" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Block program until the client clears the queue. Used during program shutdown. You should use `shutdown()` directly in most cases.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context (default: True)", - "isOptional": false, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking (default: True)", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If ``api_key`` is missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.19.0.json b/references/posthog-python-references-7.19.0.json deleted file mode 100644 index efe2ea4bc..000000000 --- a/references/posthog-python-references-7.19.0.json +++ /dev/null @@ -1,2948 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.19.0", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Optional[str]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Optional[str]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "Optional callback invoked by background consumers when an upload fails.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries for background consumers.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "If True, send each event synchronously instead of using background worker threads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Personal API key used for local feature flag evaluation and remote config payloads.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "_dedicated_ai_endpoint", - "description": "", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "any" - }, - { - "name": "uuid", - "description": "A unique identifier for the event.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "dict[str, str]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys to scope the underlying ``/flags`` request to a subset.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "dict" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team').", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "End the consumer thread once the queue is empty. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context.", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with posthog.new_context():\n identify_context('')\n posthog.capture('event_name')" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "any" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "any" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys. When provided, only these flags are evaluated \u2014 the underlying ``/flags`` request asks the server for just this subset, which makes the response smaller and the request cheaper. Use this when you only need a handful of flags out of many.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, FeatureFlag]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlag]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "any" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "any" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group", - "isOptional": true, - "type": "any" - }, - { - "name": "group_key", - "description": "Unique identifier of the group", - "isOptional": true, - "type": "any" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": false, - "type": "any" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Block program until the client clears the queue. Used during program shutdown. You should use `shutdown()` directly in most cases.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context (default: True)", - "isOptional": false, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking (default: True)", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If ``api_key`` is missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.19.1.json b/references/posthog-python-references-7.19.1.json deleted file mode 100644 index 153a5a63d..000000000 --- a/references/posthog-python-references-7.19.1.json +++ /dev/null @@ -1,2948 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.19.1", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Optional[str]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Optional[str]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "Optional callback invoked by background consumers when an upload fails.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries for background consumers.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "If True, send each event synchronously instead of using background worker threads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Personal API key used for local feature flag evaluation and remote config payloads.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "_dedicated_ai_endpoint", - "description": "", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "any" - }, - { - "name": "uuid", - "description": "A unique identifier for the event.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "dict[str, str]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys to scope the underlying ``/flags`` request to a subset.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "dict" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team').", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "End the consumer thread once the queue is empty. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context.", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with posthog.new_context():\n identify_context('')\n posthog.capture('event_name')" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "any" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "any" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys. When provided, only these flags are evaluated \u2014 the underlying ``/flags`` request asks the server for just this subset, which makes the response smaller and the request cheaper. Use this when you only need a handful of flags out of many.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, FeatureFlag]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlag]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "any" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "any" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group", - "isOptional": true, - "type": "any" - }, - { - "name": "group_key", - "description": "Unique identifier of the group", - "isOptional": true, - "type": "any" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": false, - "type": "any" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Block program until the client clears the queue. Used during program shutdown. You should use `shutdown()` directly in most cases.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context (default: True)", - "isOptional": false, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking (default: True)", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If ``api_key`` is missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.19.2.json b/references/posthog-python-references-7.19.2.json deleted file mode 100644 index d7130b76f..000000000 --- a/references/posthog-python-references-7.19.2.json +++ /dev/null @@ -1,2948 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.19.2", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Optional[str]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Optional[str]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "Optional callback invoked by background consumers when an upload fails.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries for background consumers.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "If True, send each event synchronously instead of using background worker threads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Personal API key used for local feature flag evaluation and remote config payloads.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "_dedicated_ai_endpoint", - "description": "", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "any" - }, - { - "name": "uuid", - "description": "A unique identifier for the event.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "dict[str, str]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys to scope the underlying ``/flags`` request to a subset.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "dict" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team').", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "End the consumer thread once the queue is empty. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context.", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with posthog.new_context():\n identify_context('')\n posthog.capture('event_name')" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "any" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "any" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys. When provided, only these flags are evaluated \u2014 the underlying ``/flags`` request asks the server for just this subset, which makes the response smaller and the request cheaper. Use this when you only need a handful of flags out of many.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, FeatureFlag]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlag]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "any" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "any" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group", - "isOptional": true, - "type": "any" - }, - { - "name": "group_key", - "description": "Unique identifier of the group", - "isOptional": true, - "type": "any" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": false, - "type": "any" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Block program until the client clears the queue. Used during program shutdown. You should use `shutdown()` directly in most cases.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context (default: True)", - "isOptional": false, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking (default: True)", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If ``api_key`` is missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.20.0.json b/references/posthog-python-references-7.20.0.json deleted file mode 100644 index e192cb541..000000000 --- a/references/posthog-python-references-7.20.0.json +++ /dev/null @@ -1,3093 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.20.0", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "Optional callback invoked by background consumers when an upload fails.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries for background consumers.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "If True, send each event synchronously instead of using background worker threads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Personal API key used for local feature flag evaluation and remote config payloads.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "_dedicated_ai_endpoint", - "description": "", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "any" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "dict[str, str]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys to scope the underlying ``/flags`` request to a subset.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "dict" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team').", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "End the consumer thread once the queue is empty. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "any" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "any" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys. When provided, only these flags are evaluated \u2014 the underlying ``/flags`` request asks the server for just this subset, which makes the response smaller and the request cheaper. Use this when you only need a handful of flags out of many.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, FeatureFlag]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlag]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "any" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "any" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group", - "isOptional": true, - "type": "any" - }, - { - "name": "group_key", - "description": "Unique identifier of the group", - "isOptional": true, - "type": "any" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": false, - "type": "any" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Block program until the client clears the queue. Used during program shutdown. You should use `shutdown()` directly in most cases.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If ``api_key`` is missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.20.1.json b/references/posthog-python-references-7.20.1.json deleted file mode 100644 index b1e79399d..000000000 --- a/references/posthog-python-references-7.20.1.json +++ /dev/null @@ -1,3093 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.20.1", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "Optional callback invoked by background consumers when an upload fails.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries for background consumers.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "If True, send each event synchronously instead of using background worker threads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Personal API key used for local feature flag evaluation and remote config payloads.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "_dedicated_ai_endpoint", - "description": "", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "any" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "dict[str, str]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys to scope the underlying ``/flags`` request to a subset.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "dict" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team').", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "End the consumer thread once the queue is empty. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "any" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "any" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys. When provided, only these flags are evaluated \u2014 the underlying ``/flags`` request asks the server for just this subset, which makes the response smaller and the request cheaper. Use this when you only need a handful of flags out of many.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, FeatureFlag]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlag]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "any" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "any" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "any" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "any" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": false, - "type": "any" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": false, - "type": "any" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": false, - "type": "any" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": false, - "type": "any" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group", - "isOptional": true, - "type": "any" - }, - { - "name": "group_key", - "description": "Unique identifier of the group", - "isOptional": true, - "type": "any" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": false, - "type": "any" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": false, - "type": "any" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": false, - "type": "any" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Block program until the client clears the queue. Used during program shutdown. You should use `shutdown()` directly in most cases.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If ``api_key`` is missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.20.2.json b/references/posthog-python-references-7.20.2.json deleted file mode 100644 index 289a7a6b2..000000000 --- a/references/posthog-python-references-7.20.2.json +++ /dev/null @@ -1,3120 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.20.2", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "Optional callback invoked by background consumers when an upload fails.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries for background consumers.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "If True, send each event synchronously instead of using background worker threads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Personal API key used for local feature flag evaluation and remote config payloads.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "_dedicated_ai_endpoint", - "description": "", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys to scope the underlying ``/flags`` request to a subset.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team').", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "End the consumer thread once the queue is empty. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": true, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys. When provided, only these flags are evaluated \u2014 the underlying ``/flags`` request asks the server for just this subset, which makes the response smaller and the request cheaper. Use this when you only need a handful of flags out of many.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": true, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Block program until the client clears the queue. Used during program shutdown. You should use `shutdown()` directly in most cases.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If ``api_key`` is missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.20.3.json b/references/posthog-python-references-7.20.3.json deleted file mode 100644 index 428eace96..000000000 --- a/references/posthog-python-references-7.20.3.json +++ /dev/null @@ -1,3147 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.20.3", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "Optional callback invoked by background consumers when an upload fails.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries for background consumers.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "If True, send each event synchronously instead of using background worker threads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Personal API key used for local feature flag evaluation and remote config payloads.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "_dedicated_ai_endpoint", - "description": "", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys to scope the underlying ``/flags`` request to a subset.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team').", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "End the consumer thread once the queue is empty. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": true, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys. When provided, only these flags are evaluated \u2014 the underlying ``/flags`` request asks the server for just this subset, which makes the response smaller and the request cheaper. Use this when you only need a handful of flags out of many.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": true, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Block program until the client clears the queue. Used during program shutdown. You should use `shutdown()` directly in most cases.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If ``api_key`` is missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.20.4.json b/references/posthog-python-references-7.20.4.json deleted file mode 100644 index b27b6d731..000000000 --- a/references/posthog-python-references-7.20.4.json +++ /dev/null @@ -1,3147 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.20.4", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "Optional callback invoked by background consumers when an upload fails.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries for background consumers.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "If True, send each event synchronously instead of using background worker threads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Personal API key used for local feature flag evaluation and remote config payloads.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "_dedicated_ai_endpoint", - "description": "", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys to scope the underlying ``/flags`` request to a subset.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team').", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "End the consumer thread once the queue is empty. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": true, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys. When provided, only these flags are evaluated \u2014 the underlying ``/flags`` request asks the server for just this subset, which makes the response smaller and the request cheaper. Use this when you only need a handful of flags out of many.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": true, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Block program until the client clears the queue. Used during program shutdown. You should use `shutdown()` directly in most cases.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If ``api_key`` is missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.20.5.json b/references/posthog-python-references-7.20.5.json deleted file mode 100644 index 0c562d176..000000000 --- a/references/posthog-python-references-7.20.5.json +++ /dev/null @@ -1,3147 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.20.5", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "Optional callback invoked by background consumers when an upload fails.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries for background consumers.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "If True, send each event synchronously instead of using background worker threads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Personal API key used for local feature flag evaluation and remote config payloads.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "_dedicated_ai_endpoint", - "description": "", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys to scope the underlying ``/flags`` request to a subset.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team').", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "End the consumer thread once the queue is empty. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": true, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys. When provided, only these flags are evaluated \u2014 the underlying ``/flags`` request asks the server for just this subset, which makes the response smaller and the request cheaper. Use this when you only need a handful of flags out of many.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": true, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Block program until the client clears the queue. Used during program shutdown. You should use `shutdown()` directly in most cases.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If ``api_key`` is missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.21.0.json b/references/posthog-python-references-7.21.0.json deleted file mode 100644 index 426559d05..000000000 --- a/references/posthog-python-references-7.21.0.json +++ /dev/null @@ -1,3147 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.21.0", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "Optional callback invoked by background consumers when an upload fails.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries for background consumers.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "If True, send each event synchronously instead of using background worker threads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Personal API key used for local feature flag evaluation and remote config payloads.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "_dedicated_ai_endpoint", - "description": "", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys to scope the underlying ``/flags`` request to a subset.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team').", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "End the consumer thread once the queue is empty. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": true, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys. When provided, only these flags are evaluated \u2014 the underlying ``/flags`` request asks the server for just this subset, which makes the response smaller and the request cheaper. Use this when you only need a handful of flags out of many.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": true, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Block program until the client clears the queue. Used during program shutdown. You should use `shutdown()` directly in most cases.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If ``api_key`` is missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.21.1.json b/references/posthog-python-references-7.21.1.json deleted file mode 100644 index 7225b2655..000000000 --- a/references/posthog-python-references-7.21.1.json +++ /dev/null @@ -1,3147 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.21.1", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "Optional callback invoked by background consumers when an upload fails.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries for background consumers.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "If True, send each event synchronously instead of using background worker threads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Personal API key used for local feature flag evaluation and remote config payloads.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "_dedicated_ai_endpoint", - "description": "", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys to scope the underlying ``/flags`` request to a subset.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team').", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "End the consumer thread once the queue is empty. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": true, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys. When provided, only these flags are evaluated \u2014 the underlying ``/flags`` request asks the server for just this subset, which makes the response smaller and the request cheaper. Use this when you only need a handful of flags out of many.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": true, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Block program until the client clears the queue. Used during program shutdown. You should use `shutdown()` directly in most cases.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If ``api_key`` is missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.21.2.json b/references/posthog-python-references-7.21.2.json deleted file mode 100644 index 0c13d2ee4..000000000 --- a/references/posthog-python-references-7.21.2.json +++ /dev/null @@ -1,3147 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.21.2", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "Optional callback invoked by background consumers when an upload fails.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries for background consumers.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "If True, send each event synchronously instead of using background worker threads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Personal API key used for local feature flag evaluation and remote config payloads.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "_dedicated_ai_endpoint", - "description": "", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys to scope the underlying ``/flags`` request to a subset.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team').", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "End the consumer thread once the queue is empty. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": true, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys. When provided, only these flags are evaluated \u2014 the underlying ``/flags`` request asks the server for just this subset, which makes the response smaller and the request cheaper. Use this when you only need a handful of flags out of many.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": true, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Block program until the client clears the queue. Used during program shutdown. You should use `shutdown()` directly in most cases.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If ``api_key`` is missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.22.0.json b/references/posthog-python-references-7.22.0.json deleted file mode 100644 index 984f0031a..000000000 --- a/references/posthog-python-references-7.22.0.json +++ /dev/null @@ -1,3171 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.22.0", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "Optional callback invoked by background consumers when an upload fails.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries for background consumers.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "If True, send each event synchronously instead of using background worker threads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "_dedicated_ai_endpoint", - "description": "", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys to scope the underlying ``/flags`` request to a subset.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team').", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "End the consumer thread once the queue is empty. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": true, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys. When provided, only these flags are evaluated \u2014 the underlying ``/flags`` request asks the server for just this subset, which makes the response smaller and the request cheaper. Use this when you only need a handful of flags out of many.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": true, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Block program until the client clears the queue. Used during program shutdown. You should use `shutdown()` directly in most cases.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If ``api_key`` is missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.22.1.json b/references/posthog-python-references-7.22.1.json deleted file mode 100644 index 8f9331e06..000000000 --- a/references/posthog-python-references-7.22.1.json +++ /dev/null @@ -1,3171 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.22.1", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "Optional callback invoked by background consumers when an upload fails.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries for background consumers.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "If True, send each event synchronously instead of using background worker threads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "_dedicated_ai_endpoint", - "description": "", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys to scope the underlying ``/flags`` request to a subset.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team').", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "End the consumer thread once the queue is empty. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": true, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys. When provided, only these flags are evaluated \u2014 the underlying ``/flags`` request asks the server for just this subset, which makes the response smaller and the request cheaper. Use this when you only need a handful of flags out of many.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": true, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Block program until the client clears the queue. Used during program shutdown. You should use `shutdown()` directly in most cases.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If ``api_key`` is missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.22.2.json b/references/posthog-python-references-7.22.2.json deleted file mode 100644 index 2f96528c5..000000000 --- a/references/posthog-python-references-7.22.2.json +++ /dev/null @@ -1,3171 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.22.2", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "Optional callback invoked by background consumers when an upload fails.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries for background consumers.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "If True, send each event synchronously instead of using background worker threads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "_dedicated_ai_endpoint", - "description": "", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys to scope the underlying ``/flags`` request to a subset.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team').", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "End the consumer thread once the queue is empty. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": true, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys. When provided, only these flags are evaluated \u2014 the underlying ``/flags`` request asks the server for just this subset, which makes the response smaller and the request cheaper. Use this when you only need a handful of flags out of many.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": true, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Block program until the client clears the queue. Used during program shutdown. You should use `shutdown()` directly in most cases.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If ``api_key`` is missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.22.3.json b/references/posthog-python-references-7.22.3.json deleted file mode 100644 index 3ccdb4b72..000000000 --- a/references/posthog-python-references-7.22.3.json +++ /dev/null @@ -1,3171 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.22.3", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "Optional callback invoked by background consumers when an upload fails.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries for background consumers.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "If True, send each event synchronously instead of using background worker threads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "_dedicated_ai_endpoint", - "description": "", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys to scope the underlying ``/flags`` request to a subset.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team').", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "End the consumer thread once the queue is empty. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": true, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys. When provided, only these flags are evaluated \u2014 the underlying ``/flags`` request asks the server for just this subset, which makes the response smaller and the request cheaper. Use this when you only need a handful of flags out of many.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": true, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Block program until the client clears the queue. Used during program shutdown. You should use `shutdown()` directly in most cases.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If ``api_key`` is missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.23.0.json b/references/posthog-python-references-7.23.0.json deleted file mode 100644 index 108cd0372..000000000 --- a/references/posthog-python-references-7.23.0.json +++ /dev/null @@ -1,3177 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.23.0", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "Optional callback invoked by background consumers when an upload fails.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries for background consumers.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "If True, send each event synchronously instead of using background worker threads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "_dedicated_ai_endpoint", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys to scope the underlying ``/flags`` request to a subset.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team').", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "End the consumer thread once the queue is empty. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": true, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys. When provided, only these flags are evaluated \u2014 the underlying ``/flags`` request asks the server for just this subset, which makes the response smaller and the request cheaper. Use this when you only need a handful of flags out of many.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": true, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Block program until the client clears the queue. Used during program shutdown. You should use `shutdown()` directly in most cases.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If ``api_key`` is missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.24.0.json b/references/posthog-python-references-7.24.0.json deleted file mode 100644 index d7e4768f0..000000000 --- a/references/posthog-python-references-7.24.0.json +++ /dev/null @@ -1,3182 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.24.0", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "Optional callback invoked by background consumers when an upload fails.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries for background consumers.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "If True, send each event synchronously instead of using background worker threads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "_dedicated_ai_endpoint", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys to scope the underlying ``/flags`` request to a subset.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team').", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "End the consumer thread once the queue is empty. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": true, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys. When provided, only these flags are evaluated \u2014 the underlying ``/flags`` request asks the server for just this subset, which makes the response smaller and the request cheaper. Use this when you only need a handful of flags out of many.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": true, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Block program until the client clears the queue. Used during program shutdown. You should use `shutdown()` directly in most cases.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If ``api_key`` is missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.25.0.json b/references/posthog-python-references-7.25.0.json deleted file mode 100644 index 059f926d3..000000000 --- a/references/posthog-python-references-7.25.0.json +++ /dev/null @@ -1,3182 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.25.0", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "Optional callback invoked by background consumers when an upload fails.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries for background consumers.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "If True, send each event synchronously instead of using background worker threads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "_dedicated_ai_endpoint", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys to scope the underlying ``/flags`` request to a subset.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team').", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "End the consumer thread once the queue is empty. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": true, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys. When provided, only these flags are evaluated \u2014 the underlying ``/flags`` request asks the server for just this subset, which makes the response smaller and the request cheaper. Use this when you only need a handful of flags out of many.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": true, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Block program until the client clears the queue. Used during program shutdown. You should use `shutdown()` directly in most cases.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If ``api_key`` is missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.26.0.json b/references/posthog-python-references-7.26.0.json deleted file mode 100644 index cc182d019..000000000 --- a/references/posthog-python-references-7.26.0.json +++ /dev/null @@ -1,3182 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.26.0", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "Optional callback invoked by background consumers when an upload fails.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries for background consumers.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "If True, send each event synchronously instead of using background worker threads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "_dedicated_ai_endpoint", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys to scope the underlying ``/flags`` request to a subset.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team').", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "End the consumer thread once the queue is empty. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": true, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys. When provided, only these flags are evaluated \u2014 the underlying ``/flags`` request asks the server for just this subset, which makes the response smaller and the request cheaper. Use this when you only need a handful of flags out of many.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": true, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Block program until the client clears the queue. Used during program shutdown. You should use `shutdown()` directly in most cases.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If ``api_key`` is missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.27.0.json b/references/posthog-python-references-7.27.0.json deleted file mode 100644 index a13cd7843..000000000 --- a/references/posthog-python-references-7.27.0.json +++ /dev/null @@ -1,3192 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.27.0", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "Optional callback invoked by background consumers when an upload fails.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries for background consumers.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "If True, send each event synchronously instead of using background worker threads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "_dedicated_ai_endpoint", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys to scope the underlying ``/flags`` request to a subset.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team').", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "End the consumer thread once the queue is empty. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": true, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys. When provided, only these flags are evaluated \u2014 the underlying ``/flags`` request asks the server for just this subset, which makes the response smaller and the request cheaper. Use this when you only need a handful of flags out of many.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": true, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Block program until the client clears the queue. Used during program shutdown. You should use `shutdown()` directly in most cases.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If ``api_key`` is missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.28.0.json b/references/posthog-python-references-7.28.0.json deleted file mode 100644 index 329a0c61b..000000000 --- a/references/posthog-python-references-7.28.0.json +++ /dev/null @@ -1,3192 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.28.0", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "Optional callback invoked by background consumers when an upload fails.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries for background consumers.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "If True, send each event synchronously instead of using background worker threads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "_dedicated_ai_endpoint", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys to scope the underlying ``/flags`` request to a subset.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team').", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "End the consumer thread once the queue is empty. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": true, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys. When provided, only these flags are evaluated \u2014 the underlying ``/flags`` request asks the server for just this subset, which makes the response smaller and the request cheaper. Use this when you only need a handful of flags out of many.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": true, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Block program until the client clears the queue. Used during program shutdown. You should use `shutdown()` directly in most cases.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If ``api_key`` is missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.29.0.json b/references/posthog-python-references-7.29.0.json deleted file mode 100644 index 3485eeacb..000000000 --- a/references/posthog-python-references-7.29.0.json +++ /dev/null @@ -1,3198 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.29.0", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "Optional callback invoked by background consumers when an upload fails.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries for background consumers.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "If True, send each event synchronously instead of using background worker threads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys to scope the underlying ``/flags`` request to a subset.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team').", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "End the consumer thread once the queue is empty. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": true, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys. When provided, only these flags are evaluated \u2014 the underlying ``/flags`` request asks the server for just this subset, which makes the response smaller and the request cheaper. Use this when you only need a handful of flags out of many.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": true, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Block program until the client clears the queue. Used during program shutdown. You should use `shutdown()` directly in most cases.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If ``api_key`` is missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.30.0.json b/references/posthog-python-references-7.30.0.json deleted file mode 100644 index 4a63f4e84..000000000 --- a/references/posthog-python-references-7.30.0.json +++ /dev/null @@ -1,3198 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.30.0", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "Optional callback invoked by background consumers when an upload fails.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries for background consumers.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "If True, send each event synchronously instead of using background worker threads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys to scope the underlying ``/flags`` request to a subset.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team').", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "End the consumer thread once the queue is empty. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": true, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys. When provided, only these flags are evaluated \u2014 the underlying ``/flags`` request asks the server for just this subset, which makes the response smaller and the request cheaper. Use this when you only need a handful of flags out of many.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": true, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Block program until the client clears the queue. Used during program shutdown. You should use `shutdown()` directly in most cases.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If ``api_key`` is missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.30.1.json b/references/posthog-python-references-7.30.1.json deleted file mode 100644 index 0f78e5991..000000000 --- a/references/posthog-python-references-7.30.1.json +++ /dev/null @@ -1,3198 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.30.1", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "Optional callback invoked by background consumers when an upload fails.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries for background consumers.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "If True, send each event synchronously instead of using background worker threads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys to scope the underlying ``/flags`` request to a subset.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team').", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "End the consumer thread once the queue is empty. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": true, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys. When provided, only these flags are evaluated \u2014 the underlying ``/flags`` request asks the server for just this subset, which makes the response smaller and the request cheaper. Use this when you only need a handful of flags out of many.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": true, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Block program until the client clears the queue. Used during program shutdown. You should use `shutdown()` directly in most cases.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If ``api_key`` is missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.31.0.json b/references/posthog-python-references-7.31.0.json deleted file mode 100644 index 8cba1982d..000000000 --- a/references/posthog-python-references-7.31.0.json +++ /dev/null @@ -1,3198 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.31.0", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "Optional callback invoked by background consumers when an upload fails.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries for background consumers.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "If True, send each event synchronously instead of using background worker threads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys to scope the underlying ``/flags`` request to a subset.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team').", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "End the consumer thread once the queue is empty. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": true, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys. When provided, only these flags are evaluated \u2014 the underlying ``/flags`` request asks the server for just this subset, which makes the response smaller and the request cheaper. Use this when you only need a handful of flags out of many.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": true, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Block program until the client clears the queue. Used during program shutdown. You should use `shutdown()` directly in most cases.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If ``api_key`` is missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.31.1.json b/references/posthog-python-references-7.31.1.json deleted file mode 100644 index 1d2185e8f..000000000 --- a/references/posthog-python-references-7.31.1.json +++ /dev/null @@ -1,3198 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.31.1", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "Optional callback invoked by background consumers when an upload fails.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries for background consumers.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "If True, send each event synchronously instead of using background worker threads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys to scope the underlying ``/flags`` request to a subset.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team').", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "End the consumer thread once the queue is empty. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": true, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys. When provided, only these flags are evaluated \u2014 the underlying ``/flags`` request asks the server for just this subset, which makes the response smaller and the request cheaper. Use this when you only need a handful of flags out of many.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": true, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Block program until the client clears the queue. Used during program shutdown. You should use `shutdown()` directly in most cases.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.32.0.json b/references/posthog-python-references-7.32.0.json deleted file mode 100644 index e11a57573..000000000 --- a/references/posthog-python-references-7.32.0.json +++ /dev/null @@ -1,3198 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.32.0", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "Optional callback invoked by background consumers when an upload fails.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries for background consumers.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "If True, send each event synchronously instead of using background worker threads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys to scope the underlying ``/flags`` request to a subset.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team').", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "End the consumer thread once the queue is empty. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": true, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys. When provided, only these flags are evaluated \u2014 the underlying ``/flags`` request asks the server for just this subset, which makes the response smaller and the request cheaper. Use this when you only need a handful of flags out of many.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": true, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Block program until the client clears the queue. Used during program shutdown. You should use `shutdown()` directly in most cases.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.33.0.json b/references/posthog-python-references-7.33.0.json deleted file mode 100644 index f8dddd8b4..000000000 --- a/references/posthog-python-references-7.33.0.json +++ /dev/null @@ -1,3198 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.33.0", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "Optional callback invoked by background consumers when an upload fails.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries for background consumers.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "If True, send each event synchronously instead of using background worker threads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys to scope the underlying ``/flags`` request to a subset.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team').", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "End the consumer thread once the queue is empty. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": true, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys. When provided, only these flags are evaluated \u2014 the underlying ``/flags`` request asks the server for just this subset, which makes the response smaller and the request cheaper. Use this when you only need a handful of flags out of many.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": true, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Block program until the client clears the queue. Used during program shutdown. You should use `shutdown()` directly in most cases.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.34.0.json b/references/posthog-python-references-7.34.0.json deleted file mode 100644 index 7308572bb..000000000 --- a/references/posthog-python-references-7.34.0.json +++ /dev/null @@ -1,3198 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.34.0", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "Optional callback invoked by background consumers when an upload fails.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries for background consumers.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "If True, send each event synchronously instead of using background worker threads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys to scope the underlying ``/flags`` request to a subset.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team').", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "End the consumer thread once the queue is empty. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": true, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys. When provided, only these flags are evaluated \u2014 the underlying ``/flags`` request asks the server for just this subset, which makes the response smaller and the request cheaper. Use this when you only need a handful of flags out of many.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": true, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Block program until the client clears the queue. Used during program shutdown. You should use `shutdown()` directly in most cases.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.35.0.json b/references/posthog-python-references-7.35.0.json deleted file mode 100644 index 0ea813726..000000000 --- a/references/posthog-python-references-7.35.0.json +++ /dev/null @@ -1,3198 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.35.0", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "Optional callback invoked by background consumers when an upload fails.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries for background consumers.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "If True, send each event synchronously instead of using background worker threads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys to scope the underlying ``/flags`` request to a subset.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team').", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "End the consumer thread once the queue is empty. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": true, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys. When provided, only these flags are evaluated \u2014 the underlying ``/flags`` request asks the server for just this subset, which makes the response smaller and the request cheaper. Use this when you only need a handful of flags out of many.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": true, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Block program until the client clears the queue. Used during program shutdown. You should use `shutdown()` directly in most cases.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.35.1.json b/references/posthog-python-references-7.35.1.json deleted file mode 100644 index 594840b1d..000000000 --- a/references/posthog-python-references-7.35.1.json +++ /dev/null @@ -1,3198 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.35.1", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "Optional callback invoked by background consumers when an upload fails.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries for background consumers.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "If True, send each event synchronously instead of using background worker threads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys to scope the underlying ``/flags`` request to a subset.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team').", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "End the consumer thread once the queue is empty. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": true, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys. When provided, only these flags are evaluated \u2014 the underlying ``/flags`` request asks the server for just this subset, which makes the response smaller and the request cheaper. Use this when you only need a handful of flags out of many.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": true, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Block program until the client clears the queue. Used during program shutdown. You should use `shutdown()` directly in most cases.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.35.2.json b/references/posthog-python-references-7.35.2.json deleted file mode 100644 index 04aab81d6..000000000 --- a/references/posthog-python-references-7.35.2.json +++ /dev/null @@ -1,3198 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.35.2", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "Optional callback invoked by background consumers when an upload fails.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries for background consumers.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "If True, send each event synchronously instead of using background worker threads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys to scope the underlying ``/flags`` request to a subset.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team').", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "End the consumer thread once the queue is empty. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": true, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys. When provided, only these flags are evaluated \u2014 the underlying ``/flags`` request asks the server for just this subset, which makes the response smaller and the request cheaper. Use this when you only need a handful of flags out of many.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": true, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Block program until the client clears the queue. Used during program shutdown. You should use `shutdown()` directly in most cases.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.35.3.json b/references/posthog-python-references-7.35.3.json deleted file mode 100644 index 40fd41b48..000000000 --- a/references/posthog-python-references-7.35.3.json +++ /dev/null @@ -1,3198 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.35.3", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "Optional callback invoked by background consumers when an upload fails.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "If True, send each event synchronously instead of using background worker threads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys to scope the underlying ``/flags`` request to a subset.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team').", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "End the consumer thread once the queue is empty. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": true, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys. When provided, only these flags are evaluated \u2014 the underlying ``/flags`` request asks the server for just this subset, which makes the response smaller and the request cheaper. Use this when you only need a handful of flags out of many.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": true, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Block program until the client clears the queue. Used during program shutdown. You should use `shutdown()` directly in most cases.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.35.4.json b/references/posthog-python-references-7.35.4.json deleted file mode 100644 index c5ed26a1d..000000000 --- a/references/posthog-python-references-7.35.4.json +++ /dev/null @@ -1,3198 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.35.4", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "Optional callback invoked by background consumers when an upload fails.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "If True, send each event synchronously instead of using background worker threads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys to scope the underlying ``/flags`` request to a subset.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team').", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "End the consumer thread once the queue is empty. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": true, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys. When provided, only these flags are evaluated \u2014 the underlying ``/flags`` request asks the server for just this subset, which makes the response smaller and the request cheaper. Use this when you only need a handful of flags out of many.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": true, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Block program until the client clears the queue. Used during program shutdown. You should use `shutdown()` directly in most cases.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.35.5.json b/references/posthog-python-references-7.35.5.json deleted file mode 100644 index 94d16f2bd..000000000 --- a/references/posthog-python-references-7.35.5.json +++ /dev/null @@ -1,3198 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.35.5", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "Optional callback invoked by background consumers when an upload fails.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "If True, send each event synchronously instead of using background worker threads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys to scope the underlying ``/flags`` request to a subset.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team').", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "End the consumer thread once the queue is empty. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": true, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys. When provided, only these flags are evaluated \u2014 the underlying ``/flags`` request asks the server for just this subset, which makes the response smaller and the request cheaper. Use this when you only need a handful of flags out of many.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": true, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Block program until the client clears the queue. Used during program shutdown. You should use `shutdown()` directly in most cases.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.36.0.json b/references/posthog-python-references-7.36.0.json deleted file mode 100644 index 08127cc8d..000000000 --- a/references/posthog-python-references-7.36.0.json +++ /dev/null @@ -1,3198 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.36.0", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "Optional callback invoked by background consumers when an upload fails.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "If True, send each event synchronously instead of using background worker threads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys to scope the underlying ``/flags`` request to a subset.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team').", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "End the consumer thread once the queue is empty. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": true, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys. When provided, only these flags are evaluated \u2014 the underlying ``/flags`` request asks the server for just this subset, which makes the response smaller and the request cheaper. Use this when you only need a handful of flags out of many.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": true, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Block program until the client clears the queue. Used during program shutdown. You should use `shutdown()` directly in most cases.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.37.0.json b/references/posthog-python-references-7.37.0.json deleted file mode 100644 index ca128b50d..000000000 --- a/references/posthog-python-references-7.37.0.json +++ /dev/null @@ -1,3198 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.37.0", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "Optional callback invoked by background consumers when an upload fails.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "If True, send each event synchronously instead of using background worker threads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys to scope the underlying ``/flags`` request to a subset.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team').", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "End the consumer thread once the queue is empty. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": true, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys. When provided, only these flags are evaluated \u2014 the underlying ``/flags`` request asks the server for just this subset, which makes the response smaller and the request cheaper. Use this when you only need a handful of flags out of many.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": true, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Block program until the client clears the queue. Used during program shutdown. You should use `shutdown()` directly in most cases.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.37.1.json b/references/posthog-python-references-7.37.1.json deleted file mode 100644 index 9bbe272ed..000000000 --- a/references/posthog-python-references-7.37.1.json +++ /dev/null @@ -1,3198 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.37.1", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "Optional callback invoked by background consumers when an upload fails.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "If True, send each event synchronously instead of using background worker threads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys to scope the underlying ``/flags`` request to a subset.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team').", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "End the consumer thread once the queue is empty. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": true, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys. When provided, only these flags are evaluated \u2014 the underlying ``/flags`` request asks the server for just this subset, which makes the response smaller and the request cheaper. Use this when you only need a handful of flags out of many.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": true, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Block program until the client clears the queue. Used during program shutdown. You should use `shutdown()` directly in most cases.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.37.2.json b/references/posthog-python-references-7.37.2.json deleted file mode 100644 index 64ffa4dcb..000000000 --- a/references/posthog-python-references-7.37.2.json +++ /dev/null @@ -1,3198 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.37.2", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "Optional callback invoked by background consumers when an upload fails.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "If True, send each event synchronously instead of using background worker threads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys to scope the underlying ``/flags`` request to a subset.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team').", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "End the consumer thread once the queue is empty. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": true, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys. When provided, only these flags are evaluated \u2014 the underlying ``/flags`` request asks the server for just this subset, which makes the response smaller and the request cheaper. Use this when you only need a handful of flags out of many.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": true, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Block program until the client clears the queue. Used during program shutdown. You should use `shutdown()` directly in most cases.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.37.3.json b/references/posthog-python-references-7.37.3.json deleted file mode 100644 index 6a7f390c5..000000000 --- a/references/posthog-python-references-7.37.3.json +++ /dev/null @@ -1,3198 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.37.3", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "Optional callback invoked by background consumers when an upload fails.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "If True, send each event synchronously instead of using background worker threads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys to scope the underlying ``/flags`` request to a subset.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team').", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "End the consumer thread once the queue is empty. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": true, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys. When provided, only these flags are evaluated \u2014 the underlying ``/flags`` request asks the server for just this subset, which makes the response smaller and the request cheaper. Use this when you only need a handful of flags out of many.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": true, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Block program until the client clears the queue. Used during program shutdown. You should use `shutdown()` directly in most cases.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.37.4.json b/references/posthog-python-references-7.37.4.json deleted file mode 100644 index 0298ee673..000000000 --- a/references/posthog-python-references-7.37.4.json +++ /dev/null @@ -1,3198 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.37.4", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "Optional callback invoked by background consumers when an upload fails.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "If True, send each event synchronously instead of using background worker threads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to. Falls back to the context distinct ID; the call is dropped with a warning if neither is available.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys to scope the underlying ``/flags`` request to a subset.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team').", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "End the consumer thread once the queue is empty. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": true, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys. When provided, only these flags are evaluated \u2014 the underlying ``/flags`` request asks the server for just this subset, which makes the response smaller and the request cheaper. Use this when you only need a handful of flags out of many.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": true, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Block program until the client clears the queue. Used during program shutdown. You should use `shutdown()` directly in most cases.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.37.5.json b/references/posthog-python-references-7.37.5.json deleted file mode 100644 index ab837be14..000000000 --- a/references/posthog-python-references-7.37.5.json +++ /dev/null @@ -1,3198 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.37.5", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "Optional callback invoked by background consumers when an upload fails.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "If True, send each event synchronously instead of using background worker threads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to. Falls back to the context distinct ID; the call is dropped with a warning if neither is available.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys to scope the underlying ``/flags`` request to a subset.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team').", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "End the consumer thread once the queue is empty. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": true, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys. When provided, only these flags are evaluated \u2014 the underlying ``/flags`` request asks the server for just this subset, which makes the response smaller and the request cheaper. Use this when you only need a handful of flags out of many.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": true, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Block program until the client clears the queue. Used during program shutdown. You should use `shutdown()` directly in most cases.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.37.6.json b/references/posthog-python-references-7.37.6.json deleted file mode 100644 index 92cb13c95..000000000 --- a/references/posthog-python-references-7.37.6.json +++ /dev/null @@ -1,3198 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.37.6", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "Optional callback invoked by background consumers when an upload fails.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "If True, send each event synchronously instead of using background worker threads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to. Falls back to the context distinct ID; the call is dropped with a warning if neither is available.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys to scope the underlying ``/flags`` request to a subset.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team').", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "End the consumer thread once the queue is empty. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": true, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys. When provided, only these flags are evaluated \u2014 the underlying ``/flags`` request asks the server for just this subset, which makes the response smaller and the request cheaper. Use this when you only need a handful of flags out of many.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": true, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Block program until the client clears the queue. Used during program shutdown. You should use `shutdown()` directly in most cases.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.38.0.json b/references/posthog-python-references-7.38.0.json deleted file mode 100644 index b53245e81..000000000 --- a/references/posthog-python-references-7.38.0.json +++ /dev/null @@ -1,3198 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.38.0", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "Optional callback invoked by background consumers when an upload fails.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "If True, send each event synchronously instead of using background worker threads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to. Falls back to the context distinct ID; the call is dropped with a warning if neither is available.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys to scope the underlying ``/flags`` request to a subset.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team').", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "End the consumer thread once the queue is empty. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": true, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys. When provided, only these flags are evaluated \u2014 the underlying ``/flags`` request asks the server for just this subset, which makes the response smaller and the request cheaper. Use this when you only need a handful of flags out of many.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": true, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Block program until the client clears the queue. Used during program shutdown. You should use `shutdown()` directly in most cases.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.38.1.json b/references/posthog-python-references-7.38.1.json deleted file mode 100644 index 35ea28a2d..000000000 --- a/references/posthog-python-references-7.38.1.json +++ /dev/null @@ -1,3198 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.38.1", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "If True, send each event synchronously instead of using background worker threads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to. Falls back to the context distinct ID; the call is dropped with a warning if neither is available.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys to scope the underlying ``/flags`` request to a subset.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team').", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and end the consumer threads. Do not use directly, call `shutdown()` instead. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss. Normally this method blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. When called directly from an SDK callback such as ``on_error``, shutdown is deferred to avoid blocking the worker that invoked the callback. If the callback must coordinate a blocking shutdown, have it signal an application-owned thread and return before that thread calls shutdown. Do not wait inside the callback for another thread or task that calls a lifecycle method.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": true, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys. When provided, only these flags are evaluated \u2014 the underlying ``/flags`` request asks the server for just this subset, which makes the response smaller and the request cheaper. Use this when you only need a handful of flags out of many.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": true, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and stop the client's background workers. Use `shutdown()` directly in most cases. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. This normally blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. Calls made directly from SDK callbacks such as ``on_error`` are deferred to avoid deadlocking the worker. If blocking completion is required, signal an application-owned thread, return from the callback, and call ``shutdown()`` from that thread. Do not wait inside a callback for another thread or task calling a lifecycle method.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.38.2.json b/references/posthog-python-references-7.38.2.json deleted file mode 100644 index 42cd80c84..000000000 --- a/references/posthog-python-references-7.38.2.json +++ /dev/null @@ -1,3198 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.38.2", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "If True, send each event synchronously instead of using background worker threads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to. Falls back to the context distinct ID; the call is dropped with a warning if neither is available.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys to scope the underlying ``/flags`` request to a subset.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team'). Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and end the consumer threads. Do not use directly, call `shutdown()` instead. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss. Normally this method blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. When called directly from an SDK callback such as ``on_error``, shutdown is deferred to avoid blocking the worker that invoked the callback. If the callback must coordinate a blocking shutdown, have it signal an application-owned thread and return before that thread calls shutdown. Do not wait inside the callback for another thread or task that calls a lifecycle method.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": true, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys. When provided, only these flags are evaluated \u2014 the underlying ``/flags`` request asks the server for just this subset, which makes the response smaller and the request cheaper. Use this when you only need a handful of flags out of many.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": true, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and stop the client's background workers. Use `shutdown()` directly in most cases. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. This normally blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. Calls made directly from SDK callbacks such as ``on_error`` are deferred to avoid deadlocking the worker. If blocking completion is required, signal an application-owned thread, return from the callback, and call ``shutdown()`` from that thread. Do not wait inside a callback for another thread or task calling a lifecycle method.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.38.3.json b/references/posthog-python-references-7.38.3.json deleted file mode 100644 index 89da44c60..000000000 --- a/references/posthog-python-references-7.38.3.json +++ /dev/null @@ -1,3198 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.38.3", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "If True, send each event synchronously instead of using background worker threads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to. Falls back to the context distinct ID; the call is dropped with a warning if neither is available.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys to scope the underlying ``/flags`` request to a subset.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team'). Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and end the consumer threads. Do not use directly, call `shutdown()` instead. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss. Normally this method blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. When called directly from an SDK callback such as ``on_error``, shutdown is deferred to avoid blocking the worker that invoked the callback. If the callback must coordinate a blocking shutdown, have it signal an application-owned thread and return before that thread calls shutdown. Do not wait inside the callback for another thread or task that calls a lifecycle method.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": true, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys. When provided, only these flags are evaluated \u2014 the underlying ``/flags`` request asks the server for just this subset, which makes the response smaller and the request cheaper. Use this when you only need a handful of flags out of many.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": true, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and stop the client's background workers. Use `shutdown()` directly in most cases. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. This normally blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. Calls made directly from SDK callbacks such as ``on_error`` are deferred to avoid deadlocking the worker. If blocking completion is required, signal an application-owned thread, return from the callback, and call ``shutdown()`` from that thread. Do not wait inside a callback for another thread or task calling a lifecycle method.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.38.4.json b/references/posthog-python-references-7.38.4.json deleted file mode 100644 index 708f6fda9..000000000 --- a/references/posthog-python-references-7.38.4.json +++ /dev/null @@ -1,3198 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.38.4", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "If True, send each event synchronously instead of using background worker threads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to. Falls back to the context distinct ID; the call is dropped with a warning if neither is available.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys to scope the underlying ``/flags`` request to a subset.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team'). Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and end the consumer threads. Do not use directly, call `shutdown()` instead. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss. Normally this method blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. When called directly from an SDK callback such as ``on_error``, shutdown is deferred to avoid blocking the worker that invoked the callback. If the callback must coordinate a blocking shutdown, have it signal an application-owned thread and return before that thread calls shutdown. Do not wait inside the callback for another thread or task that calls a lifecycle method.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": true, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys. When provided, only these flags are evaluated \u2014 the underlying ``/flags`` request asks the server for just this subset, which makes the response smaller and the request cheaper. Use this when you only need a handful of flags out of many.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": true, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and stop the client's background workers. Use `shutdown()` directly in most cases. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. This normally blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. Calls made directly from SDK callbacks such as ``on_error`` are deferred to avoid deadlocking the worker. If blocking completion is required, signal an application-owned thread, return from the callback, and call ``shutdown()`` from that thread. Do not wait inside a callback for another thread or task calling a lifecycle method.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.38.5.json b/references/posthog-python-references-7.38.5.json deleted file mode 100644 index 887b6bc9e..000000000 --- a/references/posthog-python-references-7.38.5.json +++ /dev/null @@ -1,3198 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.38.5", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "If True, send each event synchronously instead of using background worker threads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to. Falls back to the context distinct ID; the call is dropped with a warning if neither is available.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys to scope the underlying ``/flags`` request to a subset.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team'). Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and end the consumer threads. Do not use directly, call `shutdown()` instead. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss. Normally this method blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. When called directly from an SDK callback such as ``on_error``, shutdown is deferred to avoid blocking the worker that invoked the callback. If the callback must coordinate a blocking shutdown, have it signal an application-owned thread and return before that thread calls shutdown. Do not wait inside the callback for another thread or task that calls a lifecycle method.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": true, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys. When provided, only these flags are evaluated \u2014 the underlying ``/flags`` request asks the server for just this subset, which makes the response smaller and the request cheaper. Use this when you only need a handful of flags out of many.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": true, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and stop the client's background workers. Use `shutdown()` directly in most cases. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. This normally blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. Calls made directly from SDK callbacks such as ``on_error`` are deferred to avoid deadlocking the worker. If blocking completion is required, signal an application-owned thread, return from the callback, and call ``shutdown()`` from that thread. Do not wait inside a callback for another thread or task calling a lifecycle method.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.38.6.json b/references/posthog-python-references-7.38.6.json deleted file mode 100644 index 4809ea70c..000000000 --- a/references/posthog-python-references-7.38.6.json +++ /dev/null @@ -1,3198 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.38.6", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "If True, send each event synchronously instead of using background worker threads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to. Falls back to the context distinct ID; the call is dropped with a warning if neither is available.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys to scope the underlying ``/flags`` request to a subset.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team'). Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and end the consumer threads. Do not use directly, call `shutdown()` instead. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss. Normally this method blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. When called directly from an SDK callback such as ``on_error``, shutdown is deferred to avoid blocking the worker that invoked the callback. If the callback must coordinate a blocking shutdown, have it signal an application-owned thread and return before that thread calls shutdown. Do not wait inside the callback for another thread or task that calls a lifecycle method.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": true, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys. When provided, only these flags are evaluated \u2014 the underlying ``/flags`` request asks the server for just this subset, which makes the response smaller and the request cheaper. Use this when you only need a handful of flags out of many.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": true, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and stop the client's background workers. Use `shutdown()` directly in most cases. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. This normally blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. Calls made directly from SDK callbacks such as ``on_error`` are deferred to avoid deadlocking the worker. If blocking completion is required, signal an application-owned thread, return from the callback, and call ``shutdown()`` from that thread. Do not wait inside a callback for another thread or task calling a lifecycle method.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.39.0.json b/references/posthog-python-references-7.39.0.json deleted file mode 100644 index 849c00af4..000000000 --- a/references/posthog-python-references-7.39.0.json +++ /dev/null @@ -1,3265 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.39.0", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "If True, send each event synchronously instead of using background worker threads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "enable_full_ai_capture", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to. Falls back to the context distinct ID; the call is dropped with a warning if neither is available.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is queued on an isolated AI lane with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys to scope the underlying ``/flags`` request to a subset.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team'). Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and end the consumer threads. Do not use directly, call `shutdown()` instead. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss. Normally this method blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. When called directly from an SDK callback such as ``on_error``, shutdown is deferred to avoid blocking the worker that invoked the callback. If the callback must coordinate a blocking shutdown, have it signal an application-owned thread and return before that thread calls shutdown. Do not wait inside the callback for another thread or task that calls a lifecycle method.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": true, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is delivered on an isolated queue with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name, normally one of the `$ai_*` event names. **kwargs: Same optional arguments as `capture()`.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import capture_ai\n\nuuid = capture_ai(\n \"$ai_generation\",\n distinct_id=\"user_123\",\n properties={\"$ai_model\": \"gpt-5\"},\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys. When provided, only these flags are evaluated \u2014 the underlying ``/flags`` request asks the server for just this subset, which makes the response smaller and the request cheaper. Use this when you only need a handful of flags out of many.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event", - "isOptional": true, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and stop the client's background workers. Use `shutdown()` directly in most cases. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. This normally blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. Calls made directly from SDK callbacks such as ``on_error`` are deferred to avoid deadlocking the worker. If blocking completion is required, signal an application-owned thread, return from the callback, and call ``shutdown()`` from that thread. Do not wait inside a callback for another thread or task calling a lifecycle method.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.39.1.json b/references/posthog-python-references-7.39.1.json deleted file mode 100644 index 02096e1f2..000000000 --- a/references/posthog-python-references-7.39.1.json +++ /dev/null @@ -1,3265 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.39.1", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "If True, send each event synchronously instead of using background worker threads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "enable_full_ai_capture", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to. Falls back to the context distinct ID; the call is dropped with a warning if neither is available.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is queued on an isolated AI lane with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys to scope the underlying ``/flags`` request to a subset.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team'). Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and end the consumer threads. Do not use directly, call `shutdown()` instead. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss. Normally this method blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. When called directly from an SDK callback such as ``on_error``, shutdown is deferred to avoid blocking the worker that invoked the callback. If the callback must coordinate a blocking shutdown, have it signal an application-owned thread and return before that thread calls shutdown. Do not wait inside the callback for another thread or task that calls a lifecycle method.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is delivered on an isolated queue with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name, normally one of the `$ai_*` event names. **kwargs: Same optional arguments as `capture()`.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import capture_ai\n\nuuid = capture_ai(\n \"$ai_generation\",\n distinct_id=\"user_123\",\n properties={\"$ai_model\": \"gpt-5\"},\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys. When provided, only these flags are evaluated \u2014 the underlying ``/flags`` request asks the server for just this subset, which makes the response smaller and the request cheaper. Use this when you only need a handful of flags out of many.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and stop the client's background workers. Use `shutdown()` directly in most cases. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. This normally blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. Calls made directly from SDK callbacks such as ``on_error`` are deferred to avoid deadlocking the worker. If blocking completion is required, signal an application-owned thread, return from the callback, and call ``shutdown()`` from that thread. Do not wait inside a callback for another thread or task calling a lifecycle method.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.40.0.json b/references/posthog-python-references-7.40.0.json deleted file mode 100644 index 58058b3a5..000000000 --- a/references/posthog-python-references-7.40.0.json +++ /dev/null @@ -1,3265 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.40.0", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "If True, send each event synchronously instead of using background worker threads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "enable_full_ai_capture", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to. Falls back to the context distinct ID; the call is dropped with a warning if neither is available.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is queued on an isolated AI lane with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys to scope the underlying ``/flags`` request to a subset.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team'). Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and end the consumer threads. Do not use directly, call `shutdown()` instead. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss. Normally this method blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. When called directly from an SDK callback such as ``on_error``, shutdown is deferred to avoid blocking the worker that invoked the callback. If the callback must coordinate a blocking shutdown, have it signal an application-owned thread and return before that thread calls shutdown. Do not wait inside the callback for another thread or task that calls a lifecycle method.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is delivered on an isolated queue with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name, normally one of the `$ai_*` event names. **kwargs: Same optional arguments as `capture()`.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import capture_ai\n\nuuid = capture_ai(\n \"$ai_generation\",\n distinct_id=\"user_123\",\n properties={\"$ai_model\": \"gpt-5\"},\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys. When provided, only these flags are evaluated \u2014 the underlying ``/flags`` request asks the server for just this subset, which makes the response smaller and the request cheaper. Use this when you only need a handful of flags out of many.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and stop the client's background workers. Use `shutdown()` directly in most cases. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. This normally blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. Calls made directly from SDK callbacks such as ``on_error`` are deferred to avoid deadlocking the worker. If blocking completion is required, signal an application-owned thread, return from the callback, and call ``shutdown()`` from that thread. Do not wait inside a callback for another thread or task calling a lifecycle method.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.41.0.json b/references/posthog-python-references-7.41.0.json deleted file mode 100644 index 7957579be..000000000 --- a/references/posthog-python-references-7.41.0.json +++ /dev/null @@ -1,3265 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.41.0", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "If True, send each event synchronously instead of using background worker threads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "enable_full_ai_capture", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to. Falls back to the context distinct ID; the call is dropped with a warning if neither is available.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is queued on an isolated AI lane with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys to scope the underlying ``/flags`` request to a subset.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team'). Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and end the consumer threads. Do not use directly, call `shutdown()` instead. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss. Normally this method blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. When called directly from an SDK callback such as ``on_error``, shutdown is deferred to avoid blocking the worker that invoked the callback. If the callback must coordinate a blocking shutdown, have it signal an application-owned thread and return before that thread calls shutdown. Do not wait inside the callback for another thread or task that calls a lifecycle method.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is delivered on an isolated queue with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name, normally one of the `$ai_*` event names. **kwargs: Same optional arguments as `capture()`.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import capture_ai\n\nuuid = capture_ai(\n \"$ai_generation\",\n distinct_id=\"user_123\",\n properties={\"$ai_model\": \"gpt-5\"},\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys. When provided, only these flags are evaluated \u2014 the underlying ``/flags`` request asks the server for just this subset, which makes the response smaller and the request cheaper. Use this when you only need a handful of flags out of many.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and stop the client's background workers. Use `shutdown()` directly in most cases. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. This normally blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. Calls made directly from SDK callbacks such as ``on_error`` are deferred to avoid deadlocking the worker. If blocking completion is required, signal an application-owned thread, return from the callback, and call ``shutdown()`` from that thread. Do not wait inside a callback for another thread or task calling a lifecycle method.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.42.0.json b/references/posthog-python-references-7.42.0.json deleted file mode 100644 index 800c0fee5..000000000 --- a/references/posthog-python-references-7.42.0.json +++ /dev/null @@ -1,3265 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.42.0", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "If True, send each event synchronously instead of using background worker threads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "enable_full_ai_capture", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to. Falls back to the context distinct ID; the call is dropped with a warning if neither is available.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is queued on an isolated AI lane with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys to scope the underlying ``/flags`` request to a subset.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team'). Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and end the consumer threads. Do not use directly, call `shutdown()` instead. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss. Normally this method blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. When called directly from an SDK callback such as ``on_error``, shutdown is deferred to avoid blocking the worker that invoked the callback. If the callback must coordinate a blocking shutdown, have it signal an application-owned thread and return before that thread calls shutdown. Do not wait inside the callback for another thread or task that calls a lifecycle method.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is delivered on an isolated queue with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name, normally one of the `$ai_*` event names. **kwargs: Same optional arguments as `capture()`.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import capture_ai\n\nuuid = capture_ai(\n \"$ai_generation\",\n distinct_id=\"user_123\",\n properties={\"$ai_model\": \"gpt-5\"},\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys. When provided, only these flags are evaluated \u2014 the underlying ``/flags`` request asks the server for just this subset, which makes the response smaller and the request cheaper. Use this when you only need a handful of flags out of many.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and stop the client's background workers. Use `shutdown()` directly in most cases. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. This normally blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. Calls made directly from SDK callbacks such as ``on_error`` are deferred to avoid deadlocking the worker. If blocking completion is required, signal an application-owned thread, return from the callback, and call ``shutdown()`` from that thread. Do not wait inside a callback for another thread or task calling a lifecycle method.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.42.1.json b/references/posthog-python-references-7.42.1.json deleted file mode 100644 index 57708a35d..000000000 --- a/references/posthog-python-references-7.42.1.json +++ /dev/null @@ -1,3265 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.42.1", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "If True, send each event synchronously instead of using background worker threads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "enable_full_ai_capture", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to. Falls back to the context distinct ID; the call is dropped with a warning if neither is available.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is queued on an isolated AI lane with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys to scope the underlying ``/flags`` request to a subset.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team'). Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and end the consumer threads. Do not use directly, call `shutdown()` instead. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss. Normally this method blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. When called directly from an SDK callback such as ``on_error``, shutdown is deferred to avoid blocking the worker that invoked the callback. If the callback must coordinate a blocking shutdown, have it signal an application-owned thread and return before that thread calls shutdown. Do not wait inside the callback for another thread or task that calls a lifecycle method.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is delivered on an isolated queue with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name, normally one of the `$ai_*` event names. **kwargs: Same optional arguments as `capture()`.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import capture_ai\n\nuuid = capture_ai(\n \"$ai_generation\",\n distinct_id=\"user_123\",\n properties={\"$ai_model\": \"gpt-5\"},\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list of flag keys. When provided, only these flags are evaluated \u2014 the underlying ``/flags`` request asks the server for just this subset, which makes the response smaller and the request cheaper. Use this when you only need a handful of flags out of many.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and stop the client's background workers. Use `shutdown()` directly in most cases. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. This normally blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. Calls made directly from SDK callbacks such as ``on_error`` are deferred to avoid deadlocking the worker. If blocking completion is required, signal an application-owned thread, return from the callback, and call ``shutdown()`` from that thread. Do not wait inside a callback for another thread or task calling a lifecycle method.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.43.0.json b/references/posthog-python-references-7.43.0.json deleted file mode 100644 index 5c9341ab2..000000000 --- a/references/posthog-python-references-7.43.0.json +++ /dev/null @@ -1,3265 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.43.0", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "If True, send each event synchronously instead of using background worker threads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "enable_full_ai_capture", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to. Falls back to the context distinct ID; the call is dropped with a warning if neither is available.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is queued on an isolated AI lane with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional non-empty list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. An empty list is treated like ``None`` and evaluates all flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is True. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team'). Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and end the consumer threads. Do not use directly, call `shutdown()` instead. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss. Normally this method blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. When called directly from an SDK callback such as ``on_error``, shutdown is deferred to avoid blocking the worker that invoked the callback. If the callback must coordinate a blocking shutdown, have it signal an application-owned thread and return before that thread calls shutdown. Do not wait inside the callback for another thread or task that calls a lifecycle method.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is delivered on an isolated queue with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name, normally one of the `$ai_*` event names. **kwargs: Same optional arguments as `capture()`.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import capture_ai\n\nuuid = capture_ai(\n \"$ai_generation\",\n distinct_id=\"user_123\",\n properties={\"$ai_model\": \"gpt-5\"},\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation and omit flags that cannot be evaluated locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional non-empty list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. An empty list is treated like ``None`` and evaluates all flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is ``True``. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and stop the client's background workers. Use `shutdown()` directly in most cases. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. This normally blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. Calls made directly from SDK callbacks such as ``on_error`` are deferred to avoid deadlocking the worker. If blocking completion is required, signal an application-owned thread, return from the callback, and call ``shutdown()`` from that thread. Do not wait inside a callback for another thread or task calling a lifecycle method.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.44.0.json b/references/posthog-python-references-7.44.0.json deleted file mode 100644 index 371cd8024..000000000 --- a/references/posthog-python-references-7.44.0.json +++ /dev/null @@ -1,3271 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.44.0", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "If True, send each event synchronously instead of using background worker threads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "enable_full_ai_capture", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_trace_context", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to. Falls back to the context distinct ID; the call is dropped with a warning if neither is available.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is queued on an isolated AI lane with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is True. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team'). Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and end the consumer threads. Do not use directly, call `shutdown()` instead. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss. Normally this method blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. When called directly from an SDK callback such as ``on_error``, shutdown is deferred to avoid blocking the worker that invoked the callback. If the callback must coordinate a blocking shutdown, have it signal an application-owned thread and return before that thread calls shutdown. Do not wait inside the callback for another thread or task that calls a lifecycle method.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is delivered on an isolated queue with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name, normally one of the `$ai_*` event names. **kwargs: Same optional arguments as `capture()`.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import capture_ai\n\nuuid = capture_ai(\n \"$ai_generation\",\n distinct_id=\"user_123\",\n properties={\"$ai_model\": \"gpt-5\"},\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation and omit flags that cannot be evaluated locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is ``True``. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and stop the client's background workers. Use `shutdown()` directly in most cases. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. This normally blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. Calls made directly from SDK callbacks such as ``on_error`` are deferred to avoid deadlocking the worker. If blocking completion is required, signal an application-owned thread, return from the callback, and call ``shutdown()`` from that thread. Do not wait inside a callback for another thread or task calling a lifecycle method.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.44.1.json b/references/posthog-python-references-7.44.1.json deleted file mode 100644 index e9583854b..000000000 --- a/references/posthog-python-references-7.44.1.json +++ /dev/null @@ -1,3271 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.44.1", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "If True, send each event synchronously instead of using background worker threads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "enable_full_ai_capture", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_trace_context", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to. Falls back to the context distinct ID; the call is dropped with a warning if neither is available.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is queued on an isolated AI lane with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is True. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team'). Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and end the consumer threads. Do not use directly, call `shutdown()` instead. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss. Normally this method blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. When called directly from an SDK callback such as ``on_error``, shutdown is deferred to avoid blocking the worker that invoked the callback. If the callback must coordinate a blocking shutdown, have it signal an application-owned thread and return before that thread calls shutdown. Do not wait inside the callback for another thread or task that calls a lifecycle method.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is delivered on an isolated queue with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name, normally one of the `$ai_*` event names. **kwargs: Same optional arguments as `capture()`.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import capture_ai\n\nuuid = capture_ai(\n \"$ai_generation\",\n distinct_id=\"user_123\",\n properties={\"$ai_model\": \"gpt-5\"},\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation and omit flags that cannot be evaluated locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is ``True``. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and stop the client's background workers. Use `shutdown()` directly in most cases. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. This normally blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. Calls made directly from SDK callbacks such as ``on_error`` are deferred to avoid deadlocking the worker. If blocking completion is required, signal an application-owned thread, return from the callback, and call ``shutdown()`` from that thread. Do not wait inside a callback for another thread or task calling a lifecycle method.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.44.2.json b/references/posthog-python-references-7.44.2.json deleted file mode 100644 index 25e2ebad6..000000000 --- a/references/posthog-python-references-7.44.2.json +++ /dev/null @@ -1,3271 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.44.2", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "If True, send each event synchronously instead of using background worker threads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "enable_full_ai_capture", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_trace_context", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to. Falls back to the context distinct ID; the call is dropped with a warning if neither is available.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is queued on an isolated AI lane with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is True. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team'). Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and end the consumer threads. Do not use directly, call `shutdown()` instead. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss. Normally this method blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. When called directly from an SDK callback such as ``on_error``, shutdown is deferred to avoid blocking the worker that invoked the callback. If the callback must coordinate a blocking shutdown, have it signal an application-owned thread and return before that thread calls shutdown. Do not wait inside the callback for another thread or task that calls a lifecycle method.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is delivered on an isolated queue with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name, normally one of the `$ai_*` event names. **kwargs: Same optional arguments as `capture()`.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import capture_ai\n\nuuid = capture_ai(\n \"$ai_generation\",\n distinct_id=\"user_123\",\n properties={\"$ai_model\": \"gpt-5\"},\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation and omit flags that cannot be evaluated locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is ``True``. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and stop the client's background workers. Use `shutdown()` directly in most cases. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. This normally blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. Calls made directly from SDK callbacks such as ``on_error`` are deferred to avoid deadlocking the worker. If blocking completion is required, signal an application-owned thread, return from the callback, and call ``shutdown()`` from that thread. Do not wait inside a callback for another thread or task calling a lifecycle method.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.45.0.json b/references/posthog-python-references-7.45.0.json deleted file mode 100644 index b38b5cf01..000000000 --- a/references/posthog-python-references-7.45.0.json +++ /dev/null @@ -1,3271 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.45.0", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "enable_full_ai_capture", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_trace_context", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to. Falls back to the context distinct ID; the call is dropped with a warning if neither is available.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is queued on an isolated AI lane with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is True. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team'). Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and end the consumer threads. Do not use directly, call `shutdown()` instead. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss. Normally this method blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. When called directly from an SDK callback such as ``on_error``, shutdown is deferred to avoid blocking the worker that invoked the callback. If the callback must coordinate a blocking shutdown, have it signal an application-owned thread and return before that thread calls shutdown. Do not wait inside the callback for another thread or task that calls a lifecycle method.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is delivered on an isolated queue with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name, normally one of the `$ai_*` event names. **kwargs: Same optional arguments as `capture()`.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import capture_ai\n\nuuid = capture_ai(\n \"$ai_generation\",\n distinct_id=\"user_123\",\n properties={\"$ai_model\": \"gpt-5\"},\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation and omit flags that cannot be evaluated locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is ``True``. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and stop the client's background workers. Use `shutdown()` directly in most cases. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. This normally blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. Calls made directly from SDK callbacks such as ``on_error`` are deferred to avoid deadlocking the worker. If blocking completion is required, signal an application-owned thread, return from the callback, and call ``shutdown()`` from that thread. Do not wait inside a callback for another thread or task calling a lifecycle method.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.45.1.json b/references/posthog-python-references-7.45.1.json deleted file mode 100644 index 9123b7a2c..000000000 --- a/references/posthog-python-references-7.45.1.json +++ /dev/null @@ -1,3271 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.45.1", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "enable_full_ai_capture", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_trace_context", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to. Falls back to the context distinct ID; the call is dropped with a warning if neither is available.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is queued on an isolated AI lane with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is True. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team'). Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and end the consumer threads. Do not use directly, call `shutdown()` instead. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss. Normally this method blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. When called directly from an SDK callback such as ``on_error``, shutdown is deferred to avoid blocking the worker that invoked the callback. If the callback must coordinate a blocking shutdown, have it signal an application-owned thread and return before that thread calls shutdown. Do not wait inside the callback for another thread or task that calls a lifecycle method.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is delivered on an isolated queue with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name, normally one of the `$ai_*` event names. **kwargs: Same optional arguments as `capture()`.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import capture_ai\n\nuuid = capture_ai(\n \"$ai_generation\",\n distinct_id=\"user_123\",\n properties={\"$ai_model\": \"gpt-5\"},\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation and omit flags that cannot be evaluated locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is ``True``. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and stop the client's background workers. Use `shutdown()` directly in most cases. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. This normally blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. Calls made directly from SDK callbacks such as ``on_error`` are deferred to avoid deadlocking the worker. If blocking completion is required, signal an application-owned thread, return from the callback, and call ``shutdown()`` from that thread. Do not wait inside a callback for another thread or task calling a lifecycle method.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.45.2.json b/references/posthog-python-references-7.45.2.json deleted file mode 100644 index f5ccfd05f..000000000 --- a/references/posthog-python-references-7.45.2.json +++ /dev/null @@ -1,3271 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.45.2", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "enable_full_ai_capture", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_trace_context", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to. Falls back to the context distinct ID; the call is dropped with a warning if neither is available.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is queued on an isolated AI lane with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is True. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team'). Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and end the consumer threads. Do not use directly, call `shutdown()` instead. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss. Normally this method blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. When called directly from an SDK callback such as ``on_error``, shutdown is deferred to avoid blocking the worker that invoked the callback. If the callback must coordinate a blocking shutdown, have it signal an application-owned thread and return before that thread calls shutdown. Do not wait inside the callback for another thread or task that calls a lifecycle method.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is delivered on an isolated queue with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name, normally one of the `$ai_*` event names. **kwargs: Same optional arguments as `capture()`.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import capture_ai\n\nuuid = capture_ai(\n \"$ai_generation\",\n distinct_id=\"user_123\",\n properties={\"$ai_model\": \"gpt-5\"},\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation and omit flags that cannot be evaluated locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is ``True``. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and stop the client's background workers. Use `shutdown()` directly in most cases. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. This normally blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. Calls made directly from SDK callbacks such as ``on_error`` are deferred to avoid deadlocking the worker. If blocking completion is required, signal an application-owned thread, return from the callback, and call ``shutdown()`` from that thread. Do not wait inside a callback for another thread or task calling a lifecycle method.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.45.3.json b/references/posthog-python-references-7.45.3.json deleted file mode 100644 index ac56bef2b..000000000 --- a/references/posthog-python-references-7.45.3.json +++ /dev/null @@ -1,3271 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.45.3", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "enable_full_ai_capture", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_trace_context", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to. Falls back to the context distinct ID; the call is dropped with a warning if neither is available.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is queued on an isolated AI lane with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is True. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team'). Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and end the consumer threads. Do not use directly, call `shutdown()` instead. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss. Normally this method blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. When called directly from an SDK callback such as ``on_error``, shutdown is deferred to avoid blocking the worker that invoked the callback. If the callback must coordinate a blocking shutdown, have it signal an application-owned thread and return before that thread calls shutdown. Do not wait inside the callback for another thread or task that calls a lifecycle method.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is delivered on an isolated queue with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name, normally one of the `$ai_*` event names. **kwargs: Same optional arguments as `capture()`.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import capture_ai\n\nuuid = capture_ai(\n \"$ai_generation\",\n distinct_id=\"user_123\",\n properties={\"$ai_model\": \"gpt-5\"},\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation and omit flags that cannot be evaluated locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is ``True``. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and stop the client's background workers. Use `shutdown()` directly in most cases. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. This normally blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. Calls made directly from SDK callbacks such as ``on_error`` are deferred to avoid deadlocking the worker. If blocking completion is required, signal an application-owned thread, return from the callback, and call ``shutdown()`` from that thread. Do not wait inside a callback for another thread or task calling a lifecycle method.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.46.0.json b/references/posthog-python-references-7.46.0.json deleted file mode 100644 index 757e8a844..000000000 --- a/references/posthog-python-references-7.46.0.json +++ /dev/null @@ -1,3271 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.46.0", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "enable_full_ai_capture", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_trace_context", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to. Falls back to the context distinct ID; the call is dropped with a warning if neither is available.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is queued on an isolated AI lane with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is True. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team'). Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and end the consumer threads. Do not use directly, call `shutdown()` instead. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss. Normally this method blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. When called directly from an SDK callback such as ``on_error``, shutdown is deferred to avoid blocking the worker that invoked the callback. If the callback must coordinate a blocking shutdown, have it signal an application-owned thread and return before that thread calls shutdown. Do not wait inside the callback for another thread or task that calls a lifecycle method.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is delivered on an isolated queue with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name, normally one of the `$ai_*` event names. **kwargs: Same optional arguments as `capture()`.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import capture_ai\n\nuuid = capture_ai(\n \"$ai_generation\",\n distinct_id=\"user_123\",\n properties={\"$ai_model\": \"gpt-5\"},\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation and omit flags that cannot be evaluated locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is ``True``. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and stop the client's background workers. Use `shutdown()` directly in most cases. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. This normally blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. Calls made directly from SDK callbacks such as ``on_error`` are deferred to avoid deadlocking the worker. If blocking completion is required, signal an application-owned thread, return from the callback, and call ``shutdown()`` from that thread. Do not wait inside a callback for another thread or task calling a lifecycle method.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.47.0.json b/references/posthog-python-references-7.47.0.json deleted file mode 100644 index e55b6dabe..000000000 --- a/references/posthog-python-references-7.47.0.json +++ /dev/null @@ -1,3271 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.47.0", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "enable_full_ai_capture", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_trace_context", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to. Falls back to the context distinct ID; the call is dropped with a warning if neither is available.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is queued on an isolated AI lane with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is True. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team'). Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and end the consumer threads. Do not use directly, call `shutdown()` instead. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss. Normally this method blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. When called directly from an SDK callback such as ``on_error``, shutdown is deferred to avoid blocking the worker that invoked the callback. If the callback must coordinate a blocking shutdown, have it signal an application-owned thread and return before that thread calls shutdown. Do not wait inside the callback for another thread or task that calls a lifecycle method.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is delivered on an isolated queue with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name, normally one of the `$ai_*` event names. **kwargs: Same optional arguments as `capture()`.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import capture_ai\n\nuuid = capture_ai(\n \"$ai_generation\",\n distinct_id=\"user_123\",\n properties={\"$ai_model\": \"gpt-5\"},\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation and omit flags that cannot be evaluated locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is ``True``. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and stop the client's background workers. Use `shutdown()` directly in most cases. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. This normally blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. Calls made directly from SDK callbacks such as ``on_error`` are deferred to avoid deadlocking the worker. If blocking completion is required, signal an application-owned thread, return from the callback, and call ``shutdown()`` from that thread. Do not wait inside a callback for another thread or task calling a lifecycle method.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.47.1.json b/references/posthog-python-references-7.47.1.json deleted file mode 100644 index f6ff73d3b..000000000 --- a/references/posthog-python-references-7.47.1.json +++ /dev/null @@ -1,3271 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.47.1", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "enable_full_ai_capture", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_trace_context", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to. Falls back to the context distinct ID; the call is dropped with a warning if neither is available.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is queued on an isolated AI lane with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is True. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team'). Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and end the consumer threads. Do not use directly, call `shutdown()` instead. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss. Normally this method blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. When called directly from an SDK callback such as ``on_error``, shutdown is deferred to avoid blocking the worker that invoked the callback. If the callback must coordinate a blocking shutdown, have it signal an application-owned thread and return before that thread calls shutdown. Do not wait inside the callback for another thread or task that calls a lifecycle method.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is delivered on an isolated queue with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name, normally one of the `$ai_*` event names. **kwargs: Same optional arguments as `capture()`.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import capture_ai\n\nuuid = capture_ai(\n \"$ai_generation\",\n distinct_id=\"user_123\",\n properties={\"$ai_model\": \"gpt-5\"},\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation and omit flags that cannot be evaluated locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is ``True``. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and stop the client's background workers. Use `shutdown()` directly in most cases. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. This normally blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. Calls made directly from SDK callbacks such as ``on_error`` are deferred to avoid deadlocking the worker. If blocking completion is required, signal an application-owned thread, return from the callback, and call ``shutdown()`` from that thread. Do not wait inside a callback for another thread or task calling a lifecycle method.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.47.2.json b/references/posthog-python-references-7.47.2.json deleted file mode 100644 index e3c0c7714..000000000 --- a/references/posthog-python-references-7.47.2.json +++ /dev/null @@ -1,3271 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.47.2", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "enable_full_ai_capture", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_trace_context", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to. Falls back to the context distinct ID; the call is dropped with a warning if neither is available.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is queued on an isolated AI lane with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is True. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team'). Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and end the consumer threads. Do not use directly, call `shutdown()` instead. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss. Normally this method blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. When called directly from an SDK callback such as ``on_error``, shutdown is deferred to avoid blocking the worker that invoked the callback. If the callback must coordinate a blocking shutdown, have it signal an application-owned thread and return before that thread calls shutdown. Do not wait inside the callback for another thread or task that calls a lifecycle method.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is delivered on an isolated queue with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name, normally one of the `$ai_*` event names. **kwargs: Same optional arguments as `capture()`.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import capture_ai\n\nuuid = capture_ai(\n \"$ai_generation\",\n distinct_id=\"user_123\",\n properties={\"$ai_model\": \"gpt-5\"},\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation and omit flags that cannot be evaluated locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is ``True``. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and stop the client's background workers. Use `shutdown()` directly in most cases. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. This normally blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. Calls made directly from SDK callbacks such as ``on_error`` are deferred to avoid deadlocking the worker. If blocking completion is required, signal an application-owned thread, return from the callback, and call ``shutdown()`` from that thread. Do not wait inside a callback for another thread or task calling a lifecycle method.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.47.3.json b/references/posthog-python-references-7.47.3.json deleted file mode 100644 index 63185a41c..000000000 --- a/references/posthog-python-references-7.47.3.json +++ /dev/null @@ -1,3271 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.47.3", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "enable_full_ai_capture", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_trace_context", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to. Falls back to the context distinct ID; the call is dropped with a warning if neither is available.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is queued on an isolated AI lane with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is True. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team'). Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and end the consumer threads. Do not use directly, call `shutdown()` instead. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss. Normally this method blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. When called directly from an SDK callback such as ``on_error``, shutdown is deferred to avoid blocking the worker that invoked the callback. If the callback must coordinate a blocking shutdown, have it signal an application-owned thread and return before that thread calls shutdown. Do not wait inside the callback for another thread or task that calls a lifecycle method.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is delivered on an isolated queue with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name, normally one of the `$ai_*` event names. **kwargs: Same optional arguments as `capture()`.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import capture_ai\n\nuuid = capture_ai(\n \"$ai_generation\",\n distinct_id=\"user_123\",\n properties={\"$ai_model\": \"gpt-5\"},\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation and omit flags that cannot be evaluated locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is ``True``. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and stop the client's background workers. Use `shutdown()` directly in most cases. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. This normally blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. Calls made directly from SDK callbacks such as ``on_error`` are deferred to avoid deadlocking the worker. If blocking completion is required, signal an application-owned thread, return from the callback, and call ``shutdown()`` from that thread. Do not wait inside a callback for another thread or task calling a lifecycle method.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.48.0.json b/references/posthog-python-references-7.48.0.json deleted file mode 100644 index 1ab66c2f9..000000000 --- a/references/posthog-python-references-7.48.0.json +++ /dev/null @@ -1,3271 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.48.0", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "enable_full_ai_capture", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_trace_context", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to. Falls back to the context distinct ID; the call is dropped with a warning if neither is available.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is queued on an isolated AI lane with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is True. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team'). Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and end the consumer threads. Do not use directly, call `shutdown()` instead. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss. Normally this method blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. When called directly from an SDK callback such as ``on_error``, shutdown is deferred to avoid blocking the worker that invoked the callback. If the callback must coordinate a blocking shutdown, have it signal an application-owned thread and return before that thread calls shutdown. Do not wait inside the callback for another thread or task that calls a lifecycle method.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is delivered on an isolated queue with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name, normally one of the `$ai_*` event names. **kwargs: Same optional arguments as `capture()`.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import capture_ai\n\nuuid = capture_ai(\n \"$ai_generation\",\n distinct_id=\"user_123\",\n properties={\"$ai_model\": \"gpt-5\"},\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation and omit flags that cannot be evaluated locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is ``True``. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and stop the client's background workers. Use `shutdown()` directly in most cases. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. This normally blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. Calls made directly from SDK callbacks such as ``on_error`` are deferred to avoid deadlocking the worker. If blocking completion is required, signal an application-owned thread, return from the callback, and call ``shutdown()`` from that thread. Do not wait inside a callback for another thread or task calling a lifecycle method.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.49.0.json b/references/posthog-python-references-7.49.0.json deleted file mode 100644 index 0535e0a7b..000000000 --- a/references/posthog-python-references-7.49.0.json +++ /dev/null @@ -1,3271 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.49.0", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "enable_full_ai_capture", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_trace_context", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to. Falls back to the context distinct ID; the call is dropped with a warning if neither is available.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is queued on an isolated AI lane with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is True. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team'). Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and end the consumer threads. Do not use directly, call `shutdown()` instead. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss. Normally this method blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. When called directly from an SDK callback such as ``on_error``, shutdown is deferred to avoid blocking the worker that invoked the callback. If the callback must coordinate a blocking shutdown, have it signal an application-owned thread and return before that thread calls shutdown. Do not wait inside the callback for another thread or task that calls a lifecycle method.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is delivered on an isolated queue with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name, normally one of the `$ai_*` event names. **kwargs: Same optional arguments as `capture()`.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import capture_ai\n\nuuid = capture_ai(\n \"$ai_generation\",\n distinct_id=\"user_123\",\n properties={\"$ai_model\": \"gpt-5\"},\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation and omit flags that cannot be evaluated locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is ``True``. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and stop the client's background workers. Use `shutdown()` directly in most cases. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. This normally blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. Calls made directly from SDK callbacks such as ``on_error`` are deferred to avoid deadlocking the worker. If blocking completion is required, signal an application-owned thread, return from the callback, and call ``shutdown()`` from that thread. Do not wait inside a callback for another thread or task calling a lifecycle method.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.50.0.json b/references/posthog-python-references-7.50.0.json deleted file mode 100644 index 3203eed36..000000000 --- a/references/posthog-python-references-7.50.0.json +++ /dev/null @@ -1,3271 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.50.0", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "enable_full_ai_capture", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_trace_context", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to. Falls back to the context distinct ID; the call is dropped with a warning if neither is available.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is queued on an isolated AI lane with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is True. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team'). Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and end the consumer threads. Do not use directly, call `shutdown()` instead. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss. Normally this method blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. When called directly from an SDK callback such as ``on_error``, shutdown is deferred to avoid blocking the worker that invoked the callback. If the callback must coordinate a blocking shutdown, have it signal an application-owned thread and return before that thread calls shutdown. Do not wait inside the callback for another thread or task that calls a lifecycle method.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is delivered on an isolated queue with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name, normally one of the `$ai_*` event names. **kwargs: Same optional arguments as `capture()`.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import capture_ai\n\nuuid = capture_ai(\n \"$ai_generation\",\n distinct_id=\"user_123\",\n properties={\"$ai_model\": \"gpt-5\"},\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation and omit flags that cannot be evaluated locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is ``True``. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and stop the client's background workers. Use `shutdown()` directly in most cases. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. This normally blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. Calls made directly from SDK callbacks such as ``on_error`` are deferred to avoid deadlocking the worker. If blocking completion is required, signal an application-owned thread, return from the callback, and call ``shutdown()`` from that thread. Do not wait inside a callback for another thread or task calling a lifecycle method.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.51.0.json b/references/posthog-python-references-7.51.0.json deleted file mode 100644 index 5237d8f7e..000000000 --- a/references/posthog-python-references-7.51.0.json +++ /dev/null @@ -1,3271 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.51.0", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "enable_full_ai_capture", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_trace_context", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to. Falls back to the context distinct ID; the call is dropped with a warning if neither is available.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is queued on an isolated AI lane with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is True. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team'). Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and end the consumer threads. Do not use directly, call `shutdown()` instead. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss. Normally this method blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. When called directly from an SDK callback such as ``on_error``, shutdown is deferred to avoid blocking the worker that invoked the callback. If the callback must coordinate a blocking shutdown, have it signal an application-owned thread and return before that thread calls shutdown. Do not wait inside the callback for another thread or task that calls a lifecycle method.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is delivered on an isolated queue with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name, normally one of the `$ai_*` event names. **kwargs: Same optional arguments as `capture()`.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import capture_ai\n\nuuid = capture_ai(\n \"$ai_generation\",\n distinct_id=\"user_123\",\n properties={\"$ai_model\": \"gpt-5\"},\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation and omit flags that cannot be evaluated locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is ``True``. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and stop the client's background workers. Use `shutdown()` directly in most cases. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. This normally blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. Calls made directly from SDK callbacks such as ``on_error`` are deferred to avoid deadlocking the worker. If blocking completion is required, signal an application-owned thread, return from the callback, and call ``shutdown()`` from that thread. Do not wait inside a callback for another thread or task calling a lifecycle method.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.51.1.json b/references/posthog-python-references-7.51.1.json deleted file mode 100644 index 484dcb8c2..000000000 --- a/references/posthog-python-references-7.51.1.json +++ /dev/null @@ -1,3271 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.51.1", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "enable_full_ai_capture", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_trace_context", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to. Falls back to the context distinct ID; the call is dropped with a warning if neither is available.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is queued on an isolated AI lane with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is True. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team'). Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and end the consumer threads. Do not use directly, call `shutdown()` instead. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss. Normally this method blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. When called directly from an SDK callback such as ``on_error``, shutdown is deferred to avoid blocking the worker that invoked the callback. If the callback must coordinate a blocking shutdown, have it signal an application-owned thread and return before that thread calls shutdown. Do not wait inside the callback for another thread or task that calls a lifecycle method.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is delivered on an isolated queue with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name, normally one of the `$ai_*` event names. **kwargs: Same optional arguments as `capture()`.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import capture_ai\n\nuuid = capture_ai(\n \"$ai_generation\",\n distinct_id=\"user_123\",\n properties={\"$ai_model\": \"gpt-5\"},\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation and omit flags that cannot be evaluated locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is ``True``. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and stop the client's background workers. Use `shutdown()` directly in most cases. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. This normally blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. Calls made directly from SDK callbacks such as ``on_error`` are deferred to avoid deadlocking the worker. If blocking completion is required, signal an application-owned thread, return from the callback, and call ``shutdown()`` from that thread. Do not wait inside a callback for another thread or task calling a lifecycle method.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.51.2.json b/references/posthog-python-references-7.51.2.json deleted file mode 100644 index 8dc52610e..000000000 --- a/references/posthog-python-references-7.51.2.json +++ /dev/null @@ -1,3271 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.51.2", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "enable_full_ai_capture", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_trace_context", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to. Falls back to the context distinct ID; the call is dropped with a warning if neither is available.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is queued on an isolated AI lane with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is True. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team'). Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and end the consumer threads. Do not use directly, call `shutdown()` instead. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss. Normally this method blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. When called directly from an SDK callback such as ``on_error``, shutdown is deferred to avoid blocking the worker that invoked the callback. If the callback must coordinate a blocking shutdown, have it signal an application-owned thread and return before that thread calls shutdown. Do not wait inside the callback for another thread or task that calls a lifecycle method.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is delivered on an isolated queue with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name, normally one of the `$ai_*` event names. **kwargs: Same optional arguments as `capture()`.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import capture_ai\n\nuuid = capture_ai(\n \"$ai_generation\",\n distinct_id=\"user_123\",\n properties={\"$ai_model\": \"gpt-5\"},\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation and omit flags that cannot be evaluated locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is ``True``. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and stop the client's background workers. Use `shutdown()` directly in most cases. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. This normally blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. Calls made directly from SDK callbacks such as ``on_error`` are deferred to avoid deadlocking the worker. If blocking completion is required, signal an application-owned thread, return from the callback, and call ``shutdown()`` from that thread. Do not wait inside a callback for another thread or task calling a lifecycle method.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.52.0.json b/references/posthog-python-references-7.52.0.json deleted file mode 100644 index a8841b991..000000000 --- a/references/posthog-python-references-7.52.0.json +++ /dev/null @@ -1,3271 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.52.0", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "enable_full_ai_capture", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_trace_context", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to. Falls back to the context distinct ID; the call is dropped with a warning if neither is available.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is queued on an isolated AI lane with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is True. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team'). Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and end the consumer threads. Do not use directly, call `shutdown()` instead. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss. Normally this method blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. When called directly from an SDK callback such as ``on_error``, shutdown is deferred to avoid blocking the worker that invoked the callback. If the callback must coordinate a blocking shutdown, have it signal an application-owned thread and return before that thread calls shutdown. Do not wait inside the callback for another thread or task that calls a lifecycle method.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is delivered on an isolated queue with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name, normally one of the `$ai_*` event names. **kwargs: Same optional arguments as `capture()`.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import capture_ai\n\nuuid = capture_ai(\n \"$ai_generation\",\n distinct_id=\"user_123\",\n properties={\"$ai_model\": \"gpt-5\"},\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation and omit flags that cannot be evaluated locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is ``True``. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and stop the client's background workers. Use `shutdown()` directly in most cases. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. This normally blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. Calls made directly from SDK callbacks such as ``on_error`` are deferred to avoid deadlocking the worker. If blocking completion is required, signal an application-owned thread, return from the callback, and call ``shutdown()`` from that thread. Do not wait inside a callback for another thread or task calling a lifecycle method.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.52.1.json b/references/posthog-python-references-7.52.1.json deleted file mode 100644 index 6421dacad..000000000 --- a/references/posthog-python-references-7.52.1.json +++ /dev/null @@ -1,3271 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.52.1", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "enable_full_ai_capture", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_trace_context", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to. Falls back to the context distinct ID; the call is dropped with a warning if neither is available.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is queued on an isolated AI lane with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is True. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team'). Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and end the consumer threads. Do not use directly, call `shutdown()` instead. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss. Normally this method blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. When called directly from an SDK callback such as ``on_error``, shutdown is deferred to avoid blocking the worker that invoked the callback. If the callback must coordinate a blocking shutdown, have it signal an application-owned thread and return before that thread calls shutdown. Do not wait inside the callback for another thread or task that calls a lifecycle method.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is delivered on an isolated queue with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name, normally one of the `$ai_*` event names. **kwargs: Same optional arguments as `capture()`.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import capture_ai\n\nuuid = capture_ai(\n \"$ai_generation\",\n distinct_id=\"user_123\",\n properties={\"$ai_model\": \"gpt-5\"},\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation and omit flags that cannot be evaluated locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is ``True``. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and stop the client's background workers. Use `shutdown()` directly in most cases. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. This normally blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. Calls made directly from SDK callbacks such as ``on_error`` are deferred to avoid deadlocking the worker. If blocking completion is required, signal an application-owned thread, return from the callback, and call ``shutdown()`` from that thread. Do not wait inside a callback for another thread or task calling a lifecycle method.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.53.0.json b/references/posthog-python-references-7.53.0.json deleted file mode 100644 index d2ebbed95..000000000 --- a/references/posthog-python-references-7.53.0.json +++ /dev/null @@ -1,3271 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.53.0", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "enable_full_ai_capture", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_trace_context", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to. Falls back to the context distinct ID; the call is dropped with a warning if neither is available.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is queued on an isolated AI lane with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is True. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team'). Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and end the consumer threads. Do not use directly, call `shutdown()` instead. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss. Normally this method blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. When called directly from an SDK callback such as ``on_error``, shutdown is deferred to avoid blocking the worker that invoked the callback. If the callback must coordinate a blocking shutdown, have it signal an application-owned thread and return before that thread calls shutdown. Do not wait inside the callback for another thread or task that calls a lifecycle method.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is delivered on an isolated queue with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name, normally one of the `$ai_*` event names. **kwargs: Same optional arguments as `capture()`.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import capture_ai\n\nuuid = capture_ai(\n \"$ai_generation\",\n distinct_id=\"user_123\",\n properties={\"$ai_model\": \"gpt-5\"},\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation and omit flags that cannot be evaluated locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is ``True``. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and stop the client's background workers. Use `shutdown()` directly in most cases. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. This normally blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. Calls made directly from SDK callbacks such as ``on_error`` are deferred to avoid deadlocking the worker. If blocking completion is required, signal an application-owned thread, return from the callback, and call ``shutdown()`` from that thread. Do not wait inside a callback for another thread or task calling a lifecycle method.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.54.0.json b/references/posthog-python-references-7.54.0.json deleted file mode 100644 index 122987642..000000000 --- a/references/posthog-python-references-7.54.0.json +++ /dev/null @@ -1,3271 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.54.0", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "enable_full_ai_capture", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_trace_context", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to. Falls back to the context distinct ID; the call is dropped with a warning if neither is available.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is queued on an isolated AI lane with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is True. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team'). Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and end the consumer threads. Do not use directly, call `shutdown()` instead. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss. Normally this method blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. When called directly from an SDK callback such as ``on_error``, shutdown is deferred to avoid blocking the worker that invoked the callback. If the callback must coordinate a blocking shutdown, have it signal an application-owned thread and return before that thread calls shutdown. Do not wait inside the callback for another thread or task that calls a lifecycle method.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is delivered on an isolated queue with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name, normally one of the `$ai_*` event names. **kwargs: Same optional arguments as `capture()`.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import capture_ai\n\nuuid = capture_ai(\n \"$ai_generation\",\n distinct_id=\"user_123\",\n properties={\"$ai_model\": \"gpt-5\"},\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation and omit flags that cannot be evaluated locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is ``True``. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and stop the client's background workers. Use `shutdown()` directly in most cases. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. This normally blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. Calls made directly from SDK callbacks such as ``on_error`` are deferred to avoid deadlocking the worker. If blocking completion is required, signal an application-owned thread, return from the callback, and call ``shutdown()`` from that thread. Do not wait inside a callback for another thread or task calling a lifecycle method.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.54.1.json b/references/posthog-python-references-7.54.1.json deleted file mode 100644 index 31ab85e19..000000000 --- a/references/posthog-python-references-7.54.1.json +++ /dev/null @@ -1,3271 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.54.1", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "enable_full_ai_capture", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_trace_context", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to. Falls back to the context distinct ID; the call is dropped with a warning if neither is available.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is queued on an isolated AI lane with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is True. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team'). Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and end the consumer threads. Do not use directly, call `shutdown()` instead. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss. Normally this method blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. When called directly from an SDK callback such as ``on_error``, shutdown is deferred to avoid blocking the worker that invoked the callback. If the callback must coordinate a blocking shutdown, have it signal an application-owned thread and return before that thread calls shutdown. Do not wait inside the callback for another thread or task that calls a lifecycle method.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is delivered on an isolated queue with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name, normally one of the `$ai_*` event names. **kwargs: Same optional arguments as `capture()`.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import capture_ai\n\nuuid = capture_ai(\n \"$ai_generation\",\n distinct_id=\"user_123\",\n properties={\"$ai_model\": \"gpt-5\"},\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation and omit flags that cannot be evaluated locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is ``True``. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and stop the client's background workers. Use `shutdown()` directly in most cases. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. This normally blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. Calls made directly from SDK callbacks such as ``on_error`` are deferred to avoid deadlocking the worker. If blocking completion is required, signal an application-owned thread, return from the callback, and call ``shutdown()`` from that thread. Do not wait inside a callback for another thread or task calling a lifecycle method.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.54.2.json b/references/posthog-python-references-7.54.2.json deleted file mode 100644 index 125311000..000000000 --- a/references/posthog-python-references-7.54.2.json +++ /dev/null @@ -1,3271 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.54.2", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "enable_full_ai_capture", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_trace_context", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to. Falls back to the context distinct ID; the call is dropped with a warning if neither is available.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is queued on an isolated AI lane with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is True. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team'). Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and end the consumer threads. Do not use directly, call `shutdown()` instead. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss. Normally this method blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. When called directly from an SDK callback such as ``on_error``, shutdown is deferred to avoid blocking the worker that invoked the callback. If the callback must coordinate a blocking shutdown, have it signal an application-owned thread and return before that thread calls shutdown. Do not wait inside the callback for another thread or task that calls a lifecycle method.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is delivered on an isolated queue with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name, normally one of the `$ai_*` event names. **kwargs: Same optional arguments as `capture()`.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import capture_ai\n\nuuid = capture_ai(\n \"$ai_generation\",\n distinct_id=\"user_123\",\n properties={\"$ai_model\": \"gpt-5\"},\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation and omit flags that cannot be evaluated locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is ``True``. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and stop the client's background workers. Use `shutdown()` directly in most cases. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. This normally blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. Calls made directly from SDK callbacks such as ``on_error`` are deferred to avoid deadlocking the worker. If blocking completion is required, signal an application-owned thread, return from the callback, and call ``shutdown()`` from that thread. Do not wait inside a callback for another thread or task calling a lifecycle method.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.55.0.json b/references/posthog-python-references-7.55.0.json deleted file mode 100644 index d8ef677de..000000000 --- a/references/posthog-python-references-7.55.0.json +++ /dev/null @@ -1,3271 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.55.0", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "enable_full_ai_capture", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_trace_context", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to. Falls back to the context distinct ID; the call is dropped with a warning if neither is available.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is queued on an isolated AI lane with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is True. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team'). Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and end the consumer threads. Do not use directly, call `shutdown()` instead. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss. Normally this method blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. When called directly from an SDK callback such as ``on_error``, shutdown is deferred to avoid blocking the worker that invoked the callback. If the callback must coordinate a blocking shutdown, have it signal an application-owned thread and return before that thread calls shutdown. Do not wait inside the callback for another thread or task that calls a lifecycle method.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is delivered on an isolated queue with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name, normally one of the `$ai_*` event names. **kwargs: Same optional arguments as `capture()`.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import capture_ai\n\nuuid = capture_ai(\n \"$ai_generation\",\n distinct_id=\"user_123\",\n properties={\"$ai_model\": \"gpt-5\"},\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation and omit flags that cannot be evaluated locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is ``True``. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and stop the client's background workers. Use `shutdown()` directly in most cases. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. This normally blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. Calls made directly from SDK callbacks such as ``on_error`` are deferred to avoid deadlocking the worker. If blocking completion is required, signal an application-owned thread, return from the callback, and call ``shutdown()`` from that thread. Do not wait inside a callback for another thread or task calling a lifecycle method.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.56.0.json b/references/posthog-python-references-7.56.0.json deleted file mode 100644 index 7298fcada..000000000 --- a/references/posthog-python-references-7.56.0.json +++ /dev/null @@ -1,3271 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.56.0", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "enable_full_ai_capture", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_trace_context", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to. Falls back to the context distinct ID; the call is dropped with a warning if neither is available.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is queued on an isolated AI lane with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is True. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team'). Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and end the consumer threads. Do not use directly, call `shutdown()` instead. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss. Normally this method blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. When called directly from an SDK callback such as ``on_error``, shutdown is deferred to avoid blocking the worker that invoked the callback. If the callback must coordinate a blocking shutdown, have it signal an application-owned thread and return before that thread calls shutdown. Do not wait inside the callback for another thread or task that calls a lifecycle method.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is delivered on an isolated queue with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name, normally one of the `$ai_*` event names. **kwargs: Same optional arguments as `capture()`.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import capture_ai\n\nuuid = capture_ai(\n \"$ai_generation\",\n distinct_id=\"user_123\",\n properties={\"$ai_model\": \"gpt-5\"},\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation and omit flags that cannot be evaluated locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is ``True``. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and stop the client's background workers. Use `shutdown()` directly in most cases. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. This normally blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. Calls made directly from SDK callbacks such as ``on_error`` are deferred to avoid deadlocking the worker. If blocking completion is required, signal an application-owned thread, return from the callback, and call ``shutdown()`` from that thread. Do not wait inside a callback for another thread or task calling a lifecycle method.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.57.0.json b/references/posthog-python-references-7.57.0.json deleted file mode 100644 index 2db1e9faf..000000000 --- a/references/posthog-python-references-7.57.0.json +++ /dev/null @@ -1,3271 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.57.0", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "enable_full_ai_capture", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_trace_context", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to. Falls back to the context distinct ID; the call is dropped with a warning if neither is available.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is queued on an isolated AI lane with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is True. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team'). Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and end the consumer threads. Do not use directly, call `shutdown()` instead. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss. Normally this method blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. When called directly from an SDK callback such as ``on_error``, shutdown is deferred to avoid blocking the worker that invoked the callback. If the callback must coordinate a blocking shutdown, have it signal an application-owned thread and return before that thread calls shutdown. Do not wait inside the callback for another thread or task that calls a lifecycle method.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is delivered on an isolated queue with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name, normally one of the `$ai_*` event names. **kwargs: Same optional arguments as `capture()`.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import capture_ai\n\nuuid = capture_ai(\n \"$ai_generation\",\n distinct_id=\"user_123\",\n properties={\"$ai_model\": \"gpt-5\"},\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation and omit flags that cannot be evaluated locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is ``True``. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and stop the client's background workers. Use `shutdown()` directly in most cases. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. This normally blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. Calls made directly from SDK callbacks such as ``on_error`` are deferred to avoid deadlocking the worker. If blocking completion is required, signal an application-owned thread, return from the callback, and call ``shutdown()`` from that thread. Do not wait inside a callback for another thread or task calling a lifecycle method.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.58.0.json b/references/posthog-python-references-7.58.0.json deleted file mode 100644 index 7717dea2f..000000000 --- a/references/posthog-python-references-7.58.0.json +++ /dev/null @@ -1,3436 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.58.0", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "enable_full_ai_capture", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_trace_context", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "traces", - "description": "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.", - "isOptional": true, - "type": "dict" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to. Falls back to the context distinct ID; the call is dropped with a warning if neither is available.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is queued on an isolated AI lane with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is True. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely. Queued spans are sent at the same time, within the same", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team'). Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and end the consumer threads. Do not use directly, call `shutdown()` instead. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss. Normally this method blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Queued spans get one final flush of up to 30 s (plus a request already in flight); any it cannot send are discarded with a warning, as are spans still open. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. When called directly from an SDK callback such as ``on_error``, shutdown is deferred to avoid blocking the worker that invoked the callback. If the callback must coordinate a blocking shutdown, have it signal an application-owned thread and return before that thread calls shutdown. Do not wait inside the callback for another thread or task that calls a lifecycle method.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span. A forked child starts with no active span; pass the parent span to continue a trace across a fork.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog = Posthog(\"\", traces={\"service_name\": \"checkout-api\"})\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is delivered on an isolated queue with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name, normally one of the `$ai_*` event names. **kwargs: Same optional arguments as `capture()`.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import capture_ai\n\nuuid = capture_ai(\n \"$ai_generation\",\n distinct_id=\"user_123\",\n properties={\"$ai_model\": \"gpt-5\"},\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation and omit flags that cannot be evaluated locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is ``True``. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and stop the client's background workers. Use `shutdown()` directly in most cases. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. This normally blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. Calls made directly from SDK callbacks such as ``on_error`` are deferred to avoid deadlocking the worker. If blocking completion is required, signal an application-owned thread, return from the callback, and call ``shutdown()`` from that thread. Do not wait inside a callback for another thread or task calling a lifecycle method.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "import posthog\nposthog.traces = {\"service_name\": \"checkout-api\"}\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Tracing", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.59.0.json b/references/posthog-python-references-7.59.0.json deleted file mode 100644 index a5ad32157..000000000 --- a/references/posthog-python-references-7.59.0.json +++ /dev/null @@ -1,3436 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.59.0", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "enable_full_ai_capture", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_trace_context", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "traces", - "description": "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.", - "isOptional": true, - "type": "dict" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to. Falls back to the context distinct ID; the call is dropped with a warning if neither is available.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is queued on an isolated AI lane with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is True. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely. Queued spans are sent at the same time, within the same", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team'). Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and end the consumer threads. Do not use directly, call `shutdown()` instead. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss. Normally this method blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Queued spans get one final flush of up to 30 s (plus a request already in flight); any it cannot send are discarded with a warning, as are spans still open. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. When called directly from an SDK callback such as ``on_error``, shutdown is deferred to avoid blocking the worker that invoked the callback. If the callback must coordinate a blocking shutdown, have it signal an application-owned thread and return before that thread calls shutdown. Do not wait inside the callback for another thread or task that calls a lifecycle method.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span. A forked child starts with no active span; pass the parent span to continue a trace across a fork.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog = Posthog(\"\", traces={\"service_name\": \"checkout-api\"})\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is delivered on an isolated queue with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name, normally one of the `$ai_*` event names. **kwargs: Same optional arguments as `capture()`.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import capture_ai\n\nuuid = capture_ai(\n \"$ai_generation\",\n distinct_id=\"user_123\",\n properties={\"$ai_model\": \"gpt-5\"},\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation and omit flags that cannot be evaluated locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is ``True``. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and stop the client's background workers. Use `shutdown()` directly in most cases. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. This normally blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. Calls made directly from SDK callbacks such as ``on_error`` are deferred to avoid deadlocking the worker. If blocking completion is required, signal an application-owned thread, return from the callback, and call ``shutdown()`` from that thread. Do not wait inside a callback for another thread or task calling a lifecycle method.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "import posthog\nposthog.traces = {\"service_name\": \"checkout-api\"}\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Tracing", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.59.1.json b/references/posthog-python-references-7.59.1.json deleted file mode 100644 index 5a71e0bf1..000000000 --- a/references/posthog-python-references-7.59.1.json +++ /dev/null @@ -1,3436 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.59.1", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "enable_full_ai_capture", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_trace_context", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "traces", - "description": "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.", - "isOptional": true, - "type": "dict" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to. Falls back to the context distinct ID; the call is dropped with a warning if neither is available.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is queued on an isolated AI lane with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is True. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely. Queued spans are sent at the same time, within the same", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team'). Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and end the consumer threads. Do not use directly, call `shutdown()` instead. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss. Normally this method blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Queued spans get one final flush of up to 30 s (plus a request already in flight); any it cannot send are discarded with a warning, as are spans still open. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. When called directly from an SDK callback such as ``on_error``, shutdown is deferred to avoid blocking the worker that invoked the callback. If the callback must coordinate a blocking shutdown, have it signal an application-owned thread and return before that thread calls shutdown. Do not wait inside the callback for another thread or task that calls a lifecycle method.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span. A forked child starts with no active span; pass the parent span to continue a trace across a fork.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog = Posthog(\"\", traces={\"service_name\": \"checkout-api\"})\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is delivered on an isolated queue with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name, normally one of the `$ai_*` event names. **kwargs: Same optional arguments as `capture()`.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import capture_ai\n\nuuid = capture_ai(\n \"$ai_generation\",\n distinct_id=\"user_123\",\n properties={\"$ai_model\": \"gpt-5\"},\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation and omit flags that cannot be evaluated locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is ``True``. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and stop the client's background workers. Use `shutdown()` directly in most cases. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. This normally blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. Calls made directly from SDK callbacks such as ``on_error`` are deferred to avoid deadlocking the worker. If blocking completion is required, signal an application-owned thread, return from the callback, and call ``shutdown()`` from that thread. Do not wait inside a callback for another thread or task calling a lifecycle method.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "import posthog\nposthog.traces = {\"service_name\": \"checkout-api\"}\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Tracing", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.59.2.json b/references/posthog-python-references-7.59.2.json deleted file mode 100644 index c3a3678d8..000000000 --- a/references/posthog-python-references-7.59.2.json +++ /dev/null @@ -1,3436 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.59.2", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "enable_full_ai_capture", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_trace_context", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "traces", - "description": "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.", - "isOptional": true, - "type": "dict" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to. Falls back to the context distinct ID; the call is dropped with a warning if neither is available.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is queued on an isolated AI lane with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is True. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely. Queued spans are sent at the same time, within the same", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user, preserving valid serialized JSON.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Optional[str]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team'). Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and end the consumer threads. Do not use directly, call `shutdown()` instead. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss. Normally this method blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Queued spans get one final flush of up to 30 s (plus a request already in flight); any it cannot send are discarded with a warning, as are spans still open. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. When called directly from an SDK callback such as ``on_error``, shutdown is deferred to avoid blocking the worker that invoked the callback. If the callback must coordinate a blocking shutdown, have it signal an application-owned thread and return before that thread calls shutdown. Do not wait inside the callback for another thread or task that calls a lifecycle method.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span. A forked child starts with no active span; pass the parent span to continue a trace across a fork.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog = Posthog(\"\", traces={\"service_name\": \"checkout-api\"})\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is delivered on an isolated queue with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name, normally one of the `$ai_*` event names. **kwargs: Same optional arguments as `capture()`.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import capture_ai\n\nuuid = capture_ai(\n \"$ai_generation\",\n distinct_id=\"user_123\",\n properties={\"$ai_model\": \"gpt-5\"},\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation and omit flags that cannot be evaluated locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is ``True``. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and stop the client's background workers. Use `shutdown()` directly in most cases. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. This normally blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. Calls made directly from SDK callbacks such as ``on_error`` are deferred to avoid deadlocking the worker. If blocking completion is required, signal an application-owned thread, return from the callback, and call ``shutdown()`` from that thread. Do not wait inside a callback for another thread or task calling a lifecycle method.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "import posthog\nposthog.traces = {\"service_name\": \"checkout-api\"}\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Tracing", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.60.0.json b/references/posthog-python-references-7.60.0.json deleted file mode 100644 index f02c72de5..000000000 --- a/references/posthog-python-references-7.60.0.json +++ /dev/null @@ -1,3548 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.60.0", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "enable_full_ai_capture", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_trace_context", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "traces", - "description": "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.", - "isOptional": true, - "type": "dict" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to. Falls back to the context distinct ID; the call is dropped with a warning if neither is available.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is queued on an isolated AI lane with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is True. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely. Queued spans are sent at the same time, within the same", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nruntime = posthog.get_feature_flag_evaluation_runtime(\"my-flag\")\nif runtime is FeatureFlagEvaluationRuntime.SERVER:\n ..." - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate. A flag set to ``FeatureFlagEvaluationRuntime.ALL`` suits either runtime, so it is returned for ``CLIENT`` and for ``SERVER``, and asking for ``ALL`` returns every loaded flag. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "The runtime to match, as a ``FeatureFlagEvaluationRuntime`` or its string value.", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nclient_keys = posthog.get_feature_flag_keys_by_evaluation_runtime(\n FeatureFlagEvaluationRuntime.CLIENT\n)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user, preserving valid serialized JSON.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Optional[str]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team'). Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and end the consumer threads. Do not use directly, call `shutdown()` instead. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss. Normally this method blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Queued spans get one final flush of up to 30 s (plus a request already in flight); any it cannot send are discarded with a warning, as are spans still open. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. When called directly from an SDK callback such as ``on_error``, shutdown is deferred to avoid blocking the worker that invoked the callback. If the callback must coordinate a blocking shutdown, have it signal an application-owned thread and return before that thread calls shutdown. Do not wait inside the callback for another thread or task that calls a lifecycle method.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span. A forked child starts with no active span; pass the parent span to continue a trace across a fork.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog = Posthog(\"\", traces={\"service_name\": \"checkout-api\"})\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is delivered on an isolated queue with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name, normally one of the `$ai_*` event names. **kwargs: Same optional arguments as `capture()`.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import capture_ai\n\nuuid = capture_ai(\n \"$ai_generation\",\n distinct_id=\"user_123\",\n properties={\"$ai_model\": \"gpt-5\"},\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation and omit flags that cannot be evaluated locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is ``True``. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "Reads the `evaluation_runtime` each flag definition carries, so no extra request is made. Returns `None` when local evaluation has not loaded a definition for this key. A definition that carries no runtime reports `FeatureFlagEvaluationRuntime.ALL`, the default PostHog applies.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_evaluation_runtime\nruntime = get_feature_flag_evaluation_runtime(\"my-flag\")" - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate.", - "details": "A flag set to `FeatureFlagEvaluationRuntime.ALL` suits either runtime, so it is returned for `CLIENT` and for `SERVER`. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_keys_by_evaluation_runtime\nclient_keys = get_feature_flag_keys_by_evaluation_runtime(FeatureFlagEvaluationRuntime.CLIENT)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and stop the client's background workers. Use `shutdown()` directly in most cases. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. This normally blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. Calls made directly from SDK callbacks such as ``on_error`` are deferred to avoid deadlocking the worker. If blocking completion is required, signal an application-owned thread, return from the callback, and call ``shutdown()`` from that thread. Do not wait inside a callback for another thread or task calling a lifecycle method.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "import posthog\nposthog.traces = {\"service_name\": \"checkout-api\"}\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Tracing", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.60.1.json b/references/posthog-python-references-7.60.1.json deleted file mode 100644 index b9c5ba4aa..000000000 --- a/references/posthog-python-references-7.60.1.json +++ /dev/null @@ -1,3548 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.60.1", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "enable_full_ai_capture", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_trace_context", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "traces", - "description": "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.", - "isOptional": true, - "type": "dict" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to. Falls back to the context distinct ID; the call is dropped with a warning if neither is available.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is queued on an isolated AI lane with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is True. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely. Queued spans are sent at the same time, within the same", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nruntime = posthog.get_feature_flag_evaluation_runtime(\"my-flag\")\nif runtime is FeatureFlagEvaluationRuntime.SERVER:\n ..." - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate. A flag set to ``FeatureFlagEvaluationRuntime.ALL`` suits either runtime, so it is returned for ``CLIENT`` and for ``SERVER``, and asking for ``ALL`` returns every loaded flag. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "The runtime to match, as a ``FeatureFlagEvaluationRuntime`` or its string value.", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nclient_keys = posthog.get_feature_flag_keys_by_evaluation_runtime(\n FeatureFlagEvaluationRuntime.CLIENT\n)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user, preserving valid serialized JSON.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Optional[str]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team'). Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and end the consumer threads. Do not use directly, call `shutdown()` instead. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss. Normally this method blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Queued spans get one final flush of up to 30 s (plus a request already in flight); any it cannot send are discarded with a warning, as are spans still open. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. When called directly from an SDK callback such as ``on_error``, shutdown is deferred to avoid blocking the worker that invoked the callback. If the callback must coordinate a blocking shutdown, have it signal an application-owned thread and return before that thread calls shutdown. Do not wait inside the callback for another thread or task that calls a lifecycle method.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span. A forked child starts with no active span; pass the parent span to continue a trace across a fork.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog = Posthog(\"\", traces={\"service_name\": \"checkout-api\"})\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is delivered on an isolated queue with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name, normally one of the `$ai_*` event names. **kwargs: Same optional arguments as `capture()`.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import capture_ai\n\nuuid = capture_ai(\n \"$ai_generation\",\n distinct_id=\"user_123\",\n properties={\"$ai_model\": \"gpt-5\"},\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation and omit flags that cannot be evaluated locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is ``True``. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "Reads the `evaluation_runtime` each flag definition carries, so no extra request is made. Returns `None` when local evaluation has not loaded a definition for this key. A definition that carries no runtime reports `FeatureFlagEvaluationRuntime.ALL`, the default PostHog applies.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_evaluation_runtime\nruntime = get_feature_flag_evaluation_runtime(\"my-flag\")" - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate.", - "details": "A flag set to `FeatureFlagEvaluationRuntime.ALL` suits either runtime, so it is returned for `CLIENT` and for `SERVER`. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_keys_by_evaluation_runtime\nclient_keys = get_feature_flag_keys_by_evaluation_runtime(FeatureFlagEvaluationRuntime.CLIENT)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and stop the client's background workers. Use `shutdown()` directly in most cases. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. This normally blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. Calls made directly from SDK callbacks such as ``on_error`` are deferred to avoid deadlocking the worker. If blocking completion is required, signal an application-owned thread, return from the callback, and call ``shutdown()`` from that thread. Do not wait inside a callback for another thread or task calling a lifecycle method.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "import posthog\nposthog.traces = {\"service_name\": \"checkout-api\"}\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Tracing", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.61.0.json b/references/posthog-python-references-7.61.0.json deleted file mode 100644 index ed444a7ea..000000000 --- a/references/posthog-python-references-7.61.0.json +++ /dev/null @@ -1,3548 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.61.0", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "enable_full_ai_capture", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_trace_context", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "traces", - "description": "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.", - "isOptional": true, - "type": "dict" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to. Falls back to the context distinct ID; the call is dropped with a warning if neither is available.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is queued on an isolated AI lane with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is True. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely. Queued spans are sent at the same time, within the same", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nruntime = posthog.get_feature_flag_evaluation_runtime(\"my-flag\")\nif runtime is FeatureFlagEvaluationRuntime.SERVER:\n ..." - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate. A flag set to ``FeatureFlagEvaluationRuntime.ALL`` suits either runtime, so it is returned for ``CLIENT`` and for ``SERVER``, and asking for ``ALL`` returns every loaded flag. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "The runtime to match, as a ``FeatureFlagEvaluationRuntime`` or its string value.", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nclient_keys = posthog.get_feature_flag_keys_by_evaluation_runtime(\n FeatureFlagEvaluationRuntime.CLIENT\n)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user, preserving valid serialized JSON.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Optional[str]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team'). Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and end the consumer threads. Do not use directly, call `shutdown()` instead. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss. Normally this method blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Queued spans get one final flush of up to 30 s (plus a request already in flight); any it cannot send are discarded with a warning, as are spans still open. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. When called directly from an SDK callback such as ``on_error``, shutdown is deferred to avoid blocking the worker that invoked the callback. If the callback must coordinate a blocking shutdown, have it signal an application-owned thread and return before that thread calls shutdown. Do not wait inside the callback for another thread or task that calls a lifecycle method.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span. A forked child starts with no active span; pass the parent span to continue a trace across a fork.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog = Posthog(\"\", traces={\"service_name\": \"checkout-api\"})\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is delivered on an isolated queue with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name, normally one of the `$ai_*` event names. **kwargs: Same optional arguments as `capture()`.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import capture_ai\n\nuuid = capture_ai(\n \"$ai_generation\",\n distinct_id=\"user_123\",\n properties={\"$ai_model\": \"gpt-5\"},\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation and omit flags that cannot be evaluated locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is ``True``. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "Reads the `evaluation_runtime` each flag definition carries, so no extra request is made. Returns `None` when local evaluation has not loaded a definition for this key. A definition that carries no runtime reports `FeatureFlagEvaluationRuntime.ALL`, the default PostHog applies.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_evaluation_runtime\nruntime = get_feature_flag_evaluation_runtime(\"my-flag\")" - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate.", - "details": "A flag set to `FeatureFlagEvaluationRuntime.ALL` suits either runtime, so it is returned for `CLIENT` and for `SERVER`. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_keys_by_evaluation_runtime\nclient_keys = get_feature_flag_keys_by_evaluation_runtime(FeatureFlagEvaluationRuntime.CLIENT)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and stop the client's background workers. Use `shutdown()` directly in most cases. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. This normally blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. Calls made directly from SDK callbacks such as ``on_error`` are deferred to avoid deadlocking the worker. If blocking completion is required, signal an application-owned thread, return from the callback, and call ``shutdown()`` from that thread. Do not wait inside a callback for another thread or task calling a lifecycle method.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "import posthog\nposthog.traces = {\"service_name\": \"checkout-api\"}\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Tracing", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.61.1.json b/references/posthog-python-references-7.61.1.json deleted file mode 100644 index 2120a9f3f..000000000 --- a/references/posthog-python-references-7.61.1.json +++ /dev/null @@ -1,3548 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.61.1", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "enable_full_ai_capture", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_trace_context", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "traces", - "description": "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.", - "isOptional": true, - "type": "dict" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to. Falls back to the context distinct ID; the call is dropped with a warning if neither is available.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is queued on an isolated AI lane with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is True. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely. Queued spans are sent at the same time, within the same", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nruntime = posthog.get_feature_flag_evaluation_runtime(\"my-flag\")\nif runtime is FeatureFlagEvaluationRuntime.SERVER:\n ..." - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate. A flag set to ``FeatureFlagEvaluationRuntime.ALL`` suits either runtime, so it is returned for ``CLIENT`` and for ``SERVER``, and asking for ``ALL`` returns every loaded flag. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "The runtime to match, as a ``FeatureFlagEvaluationRuntime`` or its string value.", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nclient_keys = posthog.get_feature_flag_keys_by_evaluation_runtime(\n FeatureFlagEvaluationRuntime.CLIENT\n)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user, preserving valid serialized JSON.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Optional[str]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team'). Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and end the consumer threads. Do not use directly, call `shutdown()` instead. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss. Normally this method blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Queued spans get one final flush of up to 30 s (plus a request already in flight); any it cannot send are discarded with a warning, as are spans still open. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. When called directly from an SDK callback such as ``on_error``, shutdown is deferred to avoid blocking the worker that invoked the callback. If the callback must coordinate a blocking shutdown, have it signal an application-owned thread and return before that thread calls shutdown. Do not wait inside the callback for another thread or task that calls a lifecycle method.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span. A forked child starts with no active span; pass the parent span to continue a trace across a fork.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog = Posthog(\"\", traces={\"service_name\": \"checkout-api\"})\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is delivered on an isolated queue with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name, normally one of the `$ai_*` event names. **kwargs: Same optional arguments as `capture()`.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import capture_ai\n\nuuid = capture_ai(\n \"$ai_generation\",\n distinct_id=\"user_123\",\n properties={\"$ai_model\": \"gpt-5\"},\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation and omit flags that cannot be evaluated locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is ``True``. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "Reads the `evaluation_runtime` each flag definition carries, so no extra request is made. Returns `None` when local evaluation has not loaded a definition for this key. A definition that carries no runtime reports `FeatureFlagEvaluationRuntime.ALL`, the default PostHog applies.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_evaluation_runtime\nruntime = get_feature_flag_evaluation_runtime(\"my-flag\")" - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate.", - "details": "A flag set to `FeatureFlagEvaluationRuntime.ALL` suits either runtime, so it is returned for `CLIENT` and for `SERVER`. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_keys_by_evaluation_runtime\nclient_keys = get_feature_flag_keys_by_evaluation_runtime(FeatureFlagEvaluationRuntime.CLIENT)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and stop the client's background workers. Use `shutdown()` directly in most cases. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. This normally blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. Calls made directly from SDK callbacks such as ``on_error`` are deferred to avoid deadlocking the worker. If blocking completion is required, signal an application-owned thread, return from the callback, and call ``shutdown()`` from that thread. Do not wait inside a callback for another thread or task calling a lifecycle method.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "import posthog\nposthog.traces = {\"service_name\": \"checkout-api\"}\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Tracing", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.62.0.json b/references/posthog-python-references-7.62.0.json deleted file mode 100644 index 151cec4dd..000000000 --- a/references/posthog-python-references-7.62.0.json +++ /dev/null @@ -1,3548 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.62.0", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "enable_full_ai_capture", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_trace_context", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "traces", - "description": "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.", - "isOptional": true, - "type": "dict" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to. Falls back to the context distinct ID; the call is dropped with a warning if neither is available.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is queued on an isolated AI lane with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is True. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely. Queued spans are sent at the same time, within the same", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nruntime = posthog.get_feature_flag_evaluation_runtime(\"my-flag\")\nif runtime is FeatureFlagEvaluationRuntime.SERVER:\n ..." - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate. A flag set to ``FeatureFlagEvaluationRuntime.ALL`` suits either runtime, so it is returned for ``CLIENT`` and for ``SERVER``, and asking for ``ALL`` returns every loaded flag. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "The runtime to match, as a ``FeatureFlagEvaluationRuntime`` or its string value.", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nclient_keys = posthog.get_feature_flag_keys_by_evaluation_runtime(\n FeatureFlagEvaluationRuntime.CLIENT\n)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user, preserving valid serialized JSON.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Optional[str]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team'). Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and end the consumer threads. Do not use directly, call `shutdown()` instead. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss. Normally this method blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Queued spans get one final flush of up to 30 s (plus a request already in flight); any it cannot send are discarded with a warning, as are spans still open. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. When called directly from an SDK callback such as ``on_error``, shutdown is deferred to avoid blocking the worker that invoked the callback. If the callback must coordinate a blocking shutdown, have it signal an application-owned thread and return before that thread calls shutdown. Do not wait inside the callback for another thread or task that calls a lifecycle method.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span. A forked child starts with no active span; pass the parent span to continue a trace across a fork.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog = Posthog(\"\", traces={\"service_name\": \"checkout-api\"})\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is delivered on an isolated queue with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name, normally one of the `$ai_*` event names. **kwargs: Same optional arguments as `capture()`.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import capture_ai\n\nuuid = capture_ai(\n \"$ai_generation\",\n distinct_id=\"user_123\",\n properties={\"$ai_model\": \"gpt-5\"},\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation and omit flags that cannot be evaluated locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is ``True``. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "Reads the `evaluation_runtime` each flag definition carries, so no extra request is made. Returns `None` when local evaluation has not loaded a definition for this key. A definition that carries no runtime reports `FeatureFlagEvaluationRuntime.ALL`, the default PostHog applies.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_evaluation_runtime\nruntime = get_feature_flag_evaluation_runtime(\"my-flag\")" - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate.", - "details": "A flag set to `FeatureFlagEvaluationRuntime.ALL` suits either runtime, so it is returned for `CLIENT` and for `SERVER`. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_keys_by_evaluation_runtime\nclient_keys = get_feature_flag_keys_by_evaluation_runtime(FeatureFlagEvaluationRuntime.CLIENT)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and stop the client's background workers. Use `shutdown()` directly in most cases. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. This normally blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. Calls made directly from SDK callbacks such as ``on_error`` are deferred to avoid deadlocking the worker. If blocking completion is required, signal an application-owned thread, return from the callback, and call ``shutdown()`` from that thread. Do not wait inside a callback for another thread or task calling a lifecycle method.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "import posthog\nposthog.traces = {\"service_name\": \"checkout-api\"}\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Tracing", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.62.1.json b/references/posthog-python-references-7.62.1.json deleted file mode 100644 index 23d891d60..000000000 --- a/references/posthog-python-references-7.62.1.json +++ /dev/null @@ -1,3548 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.62.1", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "enable_full_ai_capture", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_trace_context", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "traces", - "description": "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.", - "isOptional": true, - "type": "dict" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to. Falls back to the context distinct ID; the call is dropped with a warning if neither is available.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is queued on an isolated AI lane with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is True. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely. Queued spans are sent at the same time, within the same", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nruntime = posthog.get_feature_flag_evaluation_runtime(\"my-flag\")\nif runtime is FeatureFlagEvaluationRuntime.SERVER:\n ..." - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate. A flag set to ``FeatureFlagEvaluationRuntime.ALL`` suits either runtime, so it is returned for ``CLIENT`` and for ``SERVER``, and asking for ``ALL`` returns every loaded flag. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "The runtime to match, as a ``FeatureFlagEvaluationRuntime`` or its string value.", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nclient_keys = posthog.get_feature_flag_keys_by_evaluation_runtime(\n FeatureFlagEvaluationRuntime.CLIENT\n)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user, preserving valid serialized JSON.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Optional[str]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team'). Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and end the consumer threads. Do not use directly, call `shutdown()` instead. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss. Normally this method blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Queued spans get one final flush of up to 30 s (plus a request already in flight); any it cannot send are discarded with a warning, as are spans still open. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. When called directly from an SDK callback such as ``on_error``, shutdown is deferred to avoid blocking the worker that invoked the callback. If the callback must coordinate a blocking shutdown, have it signal an application-owned thread and return before that thread calls shutdown. Do not wait inside the callback for another thread or task that calls a lifecycle method.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span. A forked child starts with no active span; pass the parent span to continue a trace across a fork.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog = Posthog(\"\", traces={\"service_name\": \"checkout-api\"})\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is delivered on an isolated queue with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name, normally one of the `$ai_*` event names. **kwargs: Same optional arguments as `capture()`.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import capture_ai\n\nuuid = capture_ai(\n \"$ai_generation\",\n distinct_id=\"user_123\",\n properties={\"$ai_model\": \"gpt-5\"},\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation and omit flags that cannot be evaluated locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is ``True``. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "Reads the `evaluation_runtime` each flag definition carries, so no extra request is made. Returns `None` when local evaluation has not loaded a definition for this key. A definition that carries no runtime reports `FeatureFlagEvaluationRuntime.ALL`, the default PostHog applies.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_evaluation_runtime\nruntime = get_feature_flag_evaluation_runtime(\"my-flag\")" - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate.", - "details": "A flag set to `FeatureFlagEvaluationRuntime.ALL` suits either runtime, so it is returned for `CLIENT` and for `SERVER`. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_keys_by_evaluation_runtime\nclient_keys = get_feature_flag_keys_by_evaluation_runtime(FeatureFlagEvaluationRuntime.CLIENT)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and stop the client's background workers. Use `shutdown()` directly in most cases. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. This normally blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. Calls made directly from SDK callbacks such as ``on_error`` are deferred to avoid deadlocking the worker. If blocking completion is required, signal an application-owned thread, return from the callback, and call ``shutdown()`` from that thread. Do not wait inside a callback for another thread or task calling a lifecycle method.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "import posthog\nposthog.traces = {\"service_name\": \"checkout-api\"}\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Tracing", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.63.0.json b/references/posthog-python-references-7.63.0.json deleted file mode 100644 index 9444d858b..000000000 --- a/references/posthog-python-references-7.63.0.json +++ /dev/null @@ -1,3548 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.63.0", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "enable_full_ai_capture", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_trace_context", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "traces", - "description": "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.", - "isOptional": true, - "type": "dict" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to. Falls back to the context distinct ID; the call is dropped with a warning if neither is available.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is queued on an isolated AI lane with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is True. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely. Queued spans are sent at the same time, within the same", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nruntime = posthog.get_feature_flag_evaluation_runtime(\"my-flag\")\nif runtime is FeatureFlagEvaluationRuntime.SERVER:\n ..." - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate. A flag set to ``FeatureFlagEvaluationRuntime.ALL`` suits either runtime, so it is returned for ``CLIENT`` and for ``SERVER``, and asking for ``ALL`` returns every loaded flag. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "The runtime to match, as a ``FeatureFlagEvaluationRuntime`` or its string value.", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nclient_keys = posthog.get_feature_flag_keys_by_evaluation_runtime(\n FeatureFlagEvaluationRuntime.CLIENT\n)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user, preserving valid serialized JSON.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Optional[str]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team'). Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and end the consumer threads. Do not use directly, call `shutdown()` instead. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss. Normally this method blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Queued spans get one final flush of up to 30 s (plus a request already in flight); any it cannot send are discarded with a warning, as are spans still open. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. When called directly from an SDK callback such as ``on_error``, shutdown is deferred to avoid blocking the worker that invoked the callback. If the callback must coordinate a blocking shutdown, have it signal an application-owned thread and return before that thread calls shutdown. Do not wait inside the callback for another thread or task that calls a lifecycle method.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span. A forked child starts with no active span; pass the parent span to continue a trace across a fork.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog = Posthog(\"\", traces={\"service_name\": \"checkout-api\"})\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is delivered on an isolated queue with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name, normally one of the `$ai_*` event names. **kwargs: Same optional arguments as `capture()`.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import capture_ai\n\nuuid = capture_ai(\n \"$ai_generation\",\n distinct_id=\"user_123\",\n properties={\"$ai_model\": \"gpt-5\"},\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation and omit flags that cannot be evaluated locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is ``True``. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "Reads the `evaluation_runtime` each flag definition carries, so no extra request is made. Returns `None` when local evaluation has not loaded a definition for this key. A definition that carries no runtime reports `FeatureFlagEvaluationRuntime.ALL`, the default PostHog applies.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_evaluation_runtime\nruntime = get_feature_flag_evaluation_runtime(\"my-flag\")" - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate.", - "details": "A flag set to `FeatureFlagEvaluationRuntime.ALL` suits either runtime, so it is returned for `CLIENT` and for `SERVER`. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_keys_by_evaluation_runtime\nclient_keys = get_feature_flag_keys_by_evaluation_runtime(FeatureFlagEvaluationRuntime.CLIENT)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and stop the client's background workers. Use `shutdown()` directly in most cases. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. This normally blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. Calls made directly from SDK callbacks such as ``on_error`` are deferred to avoid deadlocking the worker. If blocking completion is required, signal an application-owned thread, return from the callback, and call ``shutdown()`` from that thread. Do not wait inside a callback for another thread or task calling a lifecycle method.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "import posthog\nposthog.traces = {\"service_name\": \"checkout-api\"}\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Tracing", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.64.0.json b/references/posthog-python-references-7.64.0.json deleted file mode 100644 index 1ee12f3db..000000000 --- a/references/posthog-python-references-7.64.0.json +++ /dev/null @@ -1,3548 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.64.0", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "enable_full_ai_capture", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_trace_context", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "traces", - "description": "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.", - "isOptional": true, - "type": "dict" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to. Falls back to the context distinct ID; the call is dropped with a warning if neither is available.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is queued on an isolated AI lane with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is True. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely. Queued spans are sent at the same time, within the same", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nruntime = posthog.get_feature_flag_evaluation_runtime(\"my-flag\")\nif runtime is FeatureFlagEvaluationRuntime.SERVER:\n ..." - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate. A flag set to ``FeatureFlagEvaluationRuntime.ALL`` suits either runtime, so it is returned for ``CLIENT`` and for ``SERVER``, and asking for ``ALL`` returns every loaded flag. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "The runtime to match, as a ``FeatureFlagEvaluationRuntime`` or its string value.", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nclient_keys = posthog.get_feature_flag_keys_by_evaluation_runtime(\n FeatureFlagEvaluationRuntime.CLIENT\n)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user, preserving valid serialized JSON.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Optional[str]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team'). Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and end the consumer threads. Do not use directly, call `shutdown()` instead. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss. Normally this method blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Queued spans get one final flush of up to 30 s (plus a request already in flight); any it cannot send are discarded with a warning, as are spans still open. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. When called directly from an SDK callback such as ``on_error``, shutdown is deferred to avoid blocking the worker that invoked the callback. If the callback must coordinate a blocking shutdown, have it signal an application-owned thread and return before that thread calls shutdown. Do not wait inside the callback for another thread or task that calls a lifecycle method.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span. A forked child starts with no active span; pass the parent span to continue a trace across a fork.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog = Posthog(\"\", traces={\"service_name\": \"checkout-api\"})\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is delivered on an isolated queue with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name, normally one of the `$ai_*` event names. **kwargs: Same optional arguments as `capture()`.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import capture_ai\n\nuuid = capture_ai(\n \"$ai_generation\",\n distinct_id=\"user_123\",\n properties={\"$ai_model\": \"gpt-5\"},\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation and omit flags that cannot be evaluated locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is ``True``. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "Reads the `evaluation_runtime` each flag definition carries, so no extra request is made. Returns `None` when local evaluation has not loaded a definition for this key. A definition that carries no runtime reports `FeatureFlagEvaluationRuntime.ALL`, the default PostHog applies.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_evaluation_runtime\nruntime = get_feature_flag_evaluation_runtime(\"my-flag\")" - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate.", - "details": "A flag set to `FeatureFlagEvaluationRuntime.ALL` suits either runtime, so it is returned for `CLIENT` and for `SERVER`. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_keys_by_evaluation_runtime\nclient_keys = get_feature_flag_keys_by_evaluation_runtime(FeatureFlagEvaluationRuntime.CLIENT)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and stop the client's background workers. Use `shutdown()` directly in most cases. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. This normally blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. Calls made directly from SDK callbacks such as ``on_error`` are deferred to avoid deadlocking the worker. If blocking completion is required, signal an application-owned thread, return from the callback, and call ``shutdown()`` from that thread. Do not wait inside a callback for another thread or task calling a lifecycle method.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "import posthog\nposthog.traces = {\"service_name\": \"checkout-api\"}\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Tracing", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.64.1.json b/references/posthog-python-references-7.64.1.json deleted file mode 100644 index a3912a89e..000000000 --- a/references/posthog-python-references-7.64.1.json +++ /dev/null @@ -1,3548 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.64.1", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "enable_full_ai_capture", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_trace_context", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "traces", - "description": "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.", - "isOptional": true, - "type": "dict" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to. Falls back to the context distinct ID; the call is dropped with a warning if neither is available.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is queued on an isolated AI lane with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is True. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely. Queued spans are sent at the same time, within the same", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nruntime = posthog.get_feature_flag_evaluation_runtime(\"my-flag\")\nif runtime is FeatureFlagEvaluationRuntime.SERVER:\n ..." - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate. A flag set to ``FeatureFlagEvaluationRuntime.ALL`` suits either runtime, so it is returned for ``CLIENT`` and for ``SERVER``, and asking for ``ALL`` returns every loaded flag. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "The runtime to match, as a ``FeatureFlagEvaluationRuntime`` or its string value.", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nclient_keys = posthog.get_feature_flag_keys_by_evaluation_runtime(\n FeatureFlagEvaluationRuntime.CLIENT\n)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user, preserving valid serialized JSON.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Optional[str]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team'). Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and end the consumer threads. Do not use directly, call `shutdown()` instead. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss. Normally this method blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Queued spans get one final flush of up to 30 s (plus a request already in flight); any it cannot send are discarded with a warning, as are spans still open. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. When called directly from an SDK callback such as ``on_error``, shutdown is deferred to avoid blocking the worker that invoked the callback. If the callback must coordinate a blocking shutdown, have it signal an application-owned thread and return before that thread calls shutdown. Do not wait inside the callback for another thread or task that calls a lifecycle method.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span. A forked child starts with no active span; pass the parent span to continue a trace across a fork.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog = Posthog(\"\", traces={\"service_name\": \"checkout-api\"})\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is delivered on an isolated queue with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name, normally one of the `$ai_*` event names. **kwargs: Same optional arguments as `capture()`.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import capture_ai\n\nuuid = capture_ai(\n \"$ai_generation\",\n distinct_id=\"user_123\",\n properties={\"$ai_model\": \"gpt-5\"},\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation and omit flags that cannot be evaluated locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is ``True``. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "Reads the `evaluation_runtime` each flag definition carries, so no extra request is made. Returns `None` when local evaluation has not loaded a definition for this key. A definition that carries no runtime reports `FeatureFlagEvaluationRuntime.ALL`, the default PostHog applies.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_evaluation_runtime\nruntime = get_feature_flag_evaluation_runtime(\"my-flag\")" - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate.", - "details": "A flag set to `FeatureFlagEvaluationRuntime.ALL` suits either runtime, so it is returned for `CLIENT` and for `SERVER`. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_keys_by_evaluation_runtime\nclient_keys = get_feature_flag_keys_by_evaluation_runtime(FeatureFlagEvaluationRuntime.CLIENT)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and stop the client's background workers. Use `shutdown()` directly in most cases. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. This normally blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. Calls made directly from SDK callbacks such as ``on_error`` are deferred to avoid deadlocking the worker. If blocking completion is required, signal an application-owned thread, return from the callback, and call ``shutdown()`` from that thread. Do not wait inside a callback for another thread or task calling a lifecycle method.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "import posthog\nposthog.traces = {\"service_name\": \"checkout-api\"}\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Tracing", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.66.0.json b/references/posthog-python-references-7.66.0.json deleted file mode 100644 index 2f919329f..000000000 --- a/references/posthog-python-references-7.66.0.json +++ /dev/null @@ -1,3548 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.66.0", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "enable_full_ai_capture", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_trace_context", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "traces", - "description": "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.", - "isOptional": true, - "type": "dict" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to. Falls back to the context distinct ID; the call is dropped with a warning if neither is available.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is queued on an isolated AI lane with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is True. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely. Queued spans are sent at the same time, within the same", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nruntime = posthog.get_feature_flag_evaluation_runtime(\"my-flag\")\nif runtime is FeatureFlagEvaluationRuntime.SERVER:\n ..." - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate. A flag set to ``FeatureFlagEvaluationRuntime.ALL`` suits either runtime, so it is returned for ``CLIENT`` and for ``SERVER``, and asking for ``ALL`` returns every loaded flag. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "The runtime to match, as a ``FeatureFlagEvaluationRuntime`` or its string value.", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nclient_keys = posthog.get_feature_flag_keys_by_evaluation_runtime(\n FeatureFlagEvaluationRuntime.CLIENT\n)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user, preserving valid serialized JSON.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Optional[str]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team'). Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and end the consumer threads. Do not use directly, call `shutdown()` instead. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss. Normally this method blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Queued spans get one final flush of up to 30 s (plus a request already in flight); any it cannot send are discarded with a warning, as are spans still open. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. When called directly from an SDK callback such as ``on_error``, shutdown is deferred to avoid blocking the worker that invoked the callback. If the callback must coordinate a blocking shutdown, have it signal an application-owned thread and return before that thread calls shutdown. Do not wait inside the callback for another thread or task that calls a lifecycle method.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span. A forked child starts with no active span; pass the parent span to continue a trace across a fork.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog = Posthog(\"\", traces={\"service_name\": \"checkout-api\"})\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is delivered on an isolated queue with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name, normally one of the `$ai_*` event names. **kwargs: Same optional arguments as `capture()`.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import capture_ai\n\nuuid = capture_ai(\n \"$ai_generation\",\n distinct_id=\"user_123\",\n properties={\"$ai_model\": \"gpt-5\"},\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip. Overriding reserved exception properties through ``properties`` is deprecated and will stop working in the next major version.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation and omit flags that cannot be evaluated locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is ``True``. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "Reads the `evaluation_runtime` each flag definition carries, so no extra request is made. Returns `None` when local evaluation has not loaded a definition for this key. A definition that carries no runtime reports `FeatureFlagEvaluationRuntime.ALL`, the default PostHog applies.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_evaluation_runtime\nruntime = get_feature_flag_evaluation_runtime(\"my-flag\")" - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate.", - "details": "A flag set to `FeatureFlagEvaluationRuntime.ALL` suits either runtime, so it is returned for `CLIENT` and for `SERVER`. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_keys_by_evaluation_runtime\nclient_keys = get_feature_flag_keys_by_evaluation_runtime(FeatureFlagEvaluationRuntime.CLIENT)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and stop the client's background workers. Use `shutdown()` directly in most cases. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. This normally blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. Calls made directly from SDK callbacks such as ``on_error`` are deferred to avoid deadlocking the worker. If blocking completion is required, signal an application-owned thread, return from the callback, and call ``shutdown()`` from that thread. Do not wait inside a callback for another thread or task calling a lifecycle method.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "import posthog\nposthog.traces = {\"service_name\": \"checkout-api\"}\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Tracing", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.67.0.json b/references/posthog-python-references-7.67.0.json deleted file mode 100644 index 600acb877..000000000 --- a/references/posthog-python-references-7.67.0.json +++ /dev/null @@ -1,3548 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.67.0", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "enable_full_ai_capture", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_trace_context", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "traces", - "description": "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.", - "isOptional": true, - "type": "dict" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to. Falls back to the context distinct ID; the call is dropped with a warning if neither is available.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is queued on an isolated AI lane with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is True. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely. Queued spans are sent at the same time, within the same", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nruntime = posthog.get_feature_flag_evaluation_runtime(\"my-flag\")\nif runtime is FeatureFlagEvaluationRuntime.SERVER:\n ..." - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate. A flag set to ``FeatureFlagEvaluationRuntime.ALL`` suits either runtime, so it is returned for ``CLIENT`` and for ``SERVER``, and asking for ``ALL`` returns every loaded flag. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "The runtime to match, as a ``FeatureFlagEvaluationRuntime`` or its string value.", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nclient_keys = posthog.get_feature_flag_keys_by_evaluation_runtime(\n FeatureFlagEvaluationRuntime.CLIENT\n)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user, preserving valid serialized JSON.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Optional[str]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team'). Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and end the consumer threads. Do not use directly, call `shutdown()` instead. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss. Normally this method blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Queued spans get one final flush of up to 30 s (plus a request already in flight); any it cannot send are discarded with a warning, as are spans still open. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. When called directly from an SDK callback such as ``on_error``, shutdown is deferred to avoid blocking the worker that invoked the callback. If the callback must coordinate a blocking shutdown, have it signal an application-owned thread and return before that thread calls shutdown. Do not wait inside the callback for another thread or task that calls a lifecycle method.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span. A forked child starts with no active span; pass the parent span to continue a trace across a fork.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog = Posthog(\"\", traces={\"service_name\": \"checkout-api\"})\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is delivered on an isolated queue with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name, normally one of the `$ai_*` event names. **kwargs: Same optional arguments as `capture()`.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import capture_ai\n\nuuid = capture_ai(\n \"$ai_generation\",\n distinct_id=\"user_123\",\n properties={\"$ai_model\": \"gpt-5\"},\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip. Overriding reserved exception properties through ``properties`` is deprecated and will stop working in the next major version.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation and omit flags that cannot be evaluated locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is ``True``. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "Reads the `evaluation_runtime` each flag definition carries, so no extra request is made. Returns `None` when local evaluation has not loaded a definition for this key. A definition that carries no runtime reports `FeatureFlagEvaluationRuntime.ALL`, the default PostHog applies.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_evaluation_runtime\nruntime = get_feature_flag_evaluation_runtime(\"my-flag\")" - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate.", - "details": "A flag set to `FeatureFlagEvaluationRuntime.ALL` suits either runtime, so it is returned for `CLIENT` and for `SERVER`. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_keys_by_evaluation_runtime\nclient_keys = get_feature_flag_keys_by_evaluation_runtime(FeatureFlagEvaluationRuntime.CLIENT)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and stop the client's background workers. Use `shutdown()` directly in most cases. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. This normally blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. Calls made directly from SDK callbacks such as ``on_error`` are deferred to avoid deadlocking the worker. If blocking completion is required, signal an application-owned thread, return from the callback, and call ``shutdown()`` from that thread. Do not wait inside a callback for another thread or task calling a lifecycle method.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "import posthog\nposthog.traces = {\"service_name\": \"checkout-api\"}\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Tracing", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.67.1.json b/references/posthog-python-references-7.67.1.json deleted file mode 100644 index 69955559b..000000000 --- a/references/posthog-python-references-7.67.1.json +++ /dev/null @@ -1,3548 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.67.1", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "enable_full_ai_capture", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_trace_context", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "traces", - "description": "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.", - "isOptional": true, - "type": "dict" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to. Falls back to the context distinct ID; the call is dropped with a warning if neither is available.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is queued on an isolated AI lane with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is True. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely. Queued spans are sent at the same time, within the same", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nruntime = posthog.get_feature_flag_evaluation_runtime(\"my-flag\")\nif runtime is FeatureFlagEvaluationRuntime.SERVER:\n ..." - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate. A flag set to ``FeatureFlagEvaluationRuntime.ALL`` suits either runtime, so it is returned for ``CLIENT`` and for ``SERVER``, and asking for ``ALL`` returns every loaded flag. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "The runtime to match, as a ``FeatureFlagEvaluationRuntime`` or its string value.", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nclient_keys = posthog.get_feature_flag_keys_by_evaluation_runtime(\n FeatureFlagEvaluationRuntime.CLIENT\n)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user, preserving valid serialized JSON.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Optional[str]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team'). Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and end the consumer threads. Do not use directly, call `shutdown()` instead. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss. Normally this method blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Queued spans get one final flush of up to 30 s (plus a request already in flight); any it cannot send are discarded with a warning, as are spans still open. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. When called directly from an SDK callback such as ``on_error``, shutdown is deferred to avoid blocking the worker that invoked the callback. If the callback must coordinate a blocking shutdown, have it signal an application-owned thread and return before that thread calls shutdown. Do not wait inside the callback for another thread or task that calls a lifecycle method.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span. A forked child starts with no active span; pass the parent span to continue a trace across a fork.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog = Posthog(\"\", traces={\"service_name\": \"checkout-api\"})\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is delivered on an isolated queue with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name, normally one of the `$ai_*` event names. **kwargs: Same optional arguments as `capture()`.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import capture_ai\n\nuuid = capture_ai(\n \"$ai_generation\",\n distinct_id=\"user_123\",\n properties={\"$ai_model\": \"gpt-5\"},\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip. Overriding reserved exception properties through ``properties`` is deprecated and will stop working in the next major version.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation and omit flags that cannot be evaluated locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is ``True``. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "Reads the `evaluation_runtime` each flag definition carries, so no extra request is made. Returns `None` when local evaluation has not loaded a definition for this key. A definition that carries no runtime reports `FeatureFlagEvaluationRuntime.ALL`, the default PostHog applies.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_evaluation_runtime\nruntime = get_feature_flag_evaluation_runtime(\"my-flag\")" - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate.", - "details": "A flag set to `FeatureFlagEvaluationRuntime.ALL` suits either runtime, so it is returned for `CLIENT` and for `SERVER`. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_keys_by_evaluation_runtime\nclient_keys = get_feature_flag_keys_by_evaluation_runtime(FeatureFlagEvaluationRuntime.CLIENT)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and stop the client's background workers. Use `shutdown()` directly in most cases. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. This normally blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. Calls made directly from SDK callbacks such as ``on_error`` are deferred to avoid deadlocking the worker. If blocking completion is required, signal an application-owned thread, return from the callback, and call ``shutdown()`` from that thread. Do not wait inside a callback for another thread or task calling a lifecycle method.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "import posthog\nposthog.traces = {\"service_name\": \"checkout-api\"}\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Tracing", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.68.0.json b/references/posthog-python-references-7.68.0.json deleted file mode 100644 index ef12885a8..000000000 --- a/references/posthog-python-references-7.68.0.json +++ /dev/null @@ -1,3548 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.68.0", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "enable_full_ai_capture", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_trace_context", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "traces", - "description": "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.", - "isOptional": true, - "type": "dict" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to. Falls back to the context distinct ID; the call is dropped with a warning if neither is available.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is queued on an isolated AI lane with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is True. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely. Queued spans are sent at the same time, within the same", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nruntime = posthog.get_feature_flag_evaluation_runtime(\"my-flag\")\nif runtime is FeatureFlagEvaluationRuntime.SERVER:\n ..." - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate. A flag set to ``FeatureFlagEvaluationRuntime.ALL`` suits either runtime, so it is returned for ``CLIENT`` and for ``SERVER``, and asking for ``ALL`` returns every loaded flag. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "The runtime to match, as a ``FeatureFlagEvaluationRuntime`` or its string value.", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nclient_keys = posthog.get_feature_flag_keys_by_evaluation_runtime(\n FeatureFlagEvaluationRuntime.CLIENT\n)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user, preserving valid serialized JSON.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Optional[str]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team'). Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and end the consumer threads. Do not use directly, call `shutdown()` instead. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss. Normally this method blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Queued spans get one final flush of up to 30 s (plus a request already in flight); any it cannot send are discarded with a warning, as are spans still open. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. When called directly from an SDK callback such as ``on_error``, shutdown is deferred to avoid blocking the worker that invoked the callback. If the callback must coordinate a blocking shutdown, have it signal an application-owned thread and return before that thread calls shutdown. Do not wait inside the callback for another thread or task that calls a lifecycle method.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span. A forked child starts with no active span; pass the parent span to continue a trace across a fork.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog = Posthog(\"\", traces={\"service_name\": \"checkout-api\"})\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is delivered on an isolated queue with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name, normally one of the `$ai_*` event names. **kwargs: Same optional arguments as `capture()`.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import capture_ai\n\nuuid = capture_ai(\n \"$ai_generation\",\n distinct_id=\"user_123\",\n properties={\"$ai_model\": \"gpt-5\"},\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip. Overriding reserved exception properties through ``properties`` is deprecated and will stop working in the next major version.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation and omit flags that cannot be evaluated locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is ``True``. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "Reads the `evaluation_runtime` each flag definition carries, so no extra request is made. Returns `None` when local evaluation has not loaded a definition for this key. A definition that carries no runtime reports `FeatureFlagEvaluationRuntime.ALL`, the default PostHog applies.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_evaluation_runtime\nruntime = get_feature_flag_evaluation_runtime(\"my-flag\")" - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate.", - "details": "A flag set to `FeatureFlagEvaluationRuntime.ALL` suits either runtime, so it is returned for `CLIENT` and for `SERVER`. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_keys_by_evaluation_runtime\nclient_keys = get_feature_flag_keys_by_evaluation_runtime(FeatureFlagEvaluationRuntime.CLIENT)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and stop the client's background workers. Use `shutdown()` directly in most cases. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. This normally blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. Calls made directly from SDK callbacks such as ``on_error`` are deferred to avoid deadlocking the worker. If blocking completion is required, signal an application-owned thread, return from the callback, and call ``shutdown()`` from that thread. Do not wait inside a callback for another thread or task calling a lifecycle method.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "import posthog\nposthog.traces = {\"service_name\": \"checkout-api\"}\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Tracing", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.69.0.json b/references/posthog-python-references-7.69.0.json deleted file mode 100644 index d407afdb1..000000000 --- a/references/posthog-python-references-7.69.0.json +++ /dev/null @@ -1,3548 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.69.0", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "enable_full_ai_capture", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_trace_context", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "traces", - "description": "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.", - "isOptional": true, - "type": "dict" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to. Falls back to the context distinct ID; the call is dropped with a warning if neither is available.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is queued on an isolated AI lane with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is True. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely. Queued spans are sent at the same time, within the same", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nruntime = posthog.get_feature_flag_evaluation_runtime(\"my-flag\")\nif runtime is FeatureFlagEvaluationRuntime.SERVER:\n ..." - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate. A flag set to ``FeatureFlagEvaluationRuntime.ALL`` suits either runtime, so it is returned for ``CLIENT`` and for ``SERVER``, and asking for ``ALL`` returns every loaded flag. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "The runtime to match, as a ``FeatureFlagEvaluationRuntime`` or its string value.", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nclient_keys = posthog.get_feature_flag_keys_by_evaluation_runtime(\n FeatureFlagEvaluationRuntime.CLIENT\n)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user, preserving valid serialized JSON.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Optional[str]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team'). Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and end the consumer threads. Do not use directly, call `shutdown()` instead. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss. Normally this method blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Queued spans get one final flush of up to 30 s (plus a request already in flight); any it cannot send are discarded with a warning, as are spans still open. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. When called directly from an SDK callback such as ``on_error``, shutdown is deferred to avoid blocking the worker that invoked the callback. If the callback must coordinate a blocking shutdown, have it signal an application-owned thread and return before that thread calls shutdown. Do not wait inside the callback for another thread or task that calls a lifecycle method.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span. A forked child starts with no active span; pass the parent span to continue a trace across a fork.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog = Posthog(\"\", traces={\"service_name\": \"checkout-api\"})\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is delivered on an isolated queue with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name, normally one of the `$ai_*` event names. **kwargs: Same optional arguments as `capture()`.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import capture_ai\n\nuuid = capture_ai(\n \"$ai_generation\",\n distinct_id=\"user_123\",\n properties={\"$ai_model\": \"gpt-5\"},\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip. Overriding reserved exception properties through ``properties`` is deprecated and will stop working in the next major version.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation and omit flags that cannot be evaluated locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is ``True``. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "Reads the `evaluation_runtime` each flag definition carries, so no extra request is made. Returns `None` when local evaluation has not loaded a definition for this key. A definition that carries no runtime reports `FeatureFlagEvaluationRuntime.ALL`, the default PostHog applies.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_evaluation_runtime\nruntime = get_feature_flag_evaluation_runtime(\"my-flag\")" - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate.", - "details": "A flag set to `FeatureFlagEvaluationRuntime.ALL` suits either runtime, so it is returned for `CLIENT` and for `SERVER`. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_keys_by_evaluation_runtime\nclient_keys = get_feature_flag_keys_by_evaluation_runtime(FeatureFlagEvaluationRuntime.CLIENT)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and stop the client's background workers. Use `shutdown()` directly in most cases. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. This normally blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. Calls made directly from SDK callbacks such as ``on_error`` are deferred to avoid deadlocking the worker. If blocking completion is required, signal an application-owned thread, return from the callback, and call ``shutdown()`` from that thread. Do not wait inside a callback for another thread or task calling a lifecycle method.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "import posthog\nposthog.traces = {\"service_name\": \"checkout-api\"}\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Tracing", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.70.0.json b/references/posthog-python-references-7.70.0.json deleted file mode 100644 index 6e46c32c7..000000000 --- a/references/posthog-python-references-7.70.0.json +++ /dev/null @@ -1,3548 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.70.0", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "enable_full_ai_capture", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_trace_context", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "traces", - "description": "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.", - "isOptional": true, - "type": "dict" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to. Falls back to the context distinct ID; the call is dropped with a warning if neither is available.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is queued on an isolated AI lane with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is True. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely. Queued spans are sent at the same time, within the same", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nruntime = posthog.get_feature_flag_evaluation_runtime(\"my-flag\")\nif runtime is FeatureFlagEvaluationRuntime.SERVER:\n ..." - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate. A flag set to ``FeatureFlagEvaluationRuntime.ALL`` suits either runtime, so it is returned for ``CLIENT`` and for ``SERVER``, and asking for ``ALL`` returns every loaded flag. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "The runtime to match, as a ``FeatureFlagEvaluationRuntime`` or its string value.", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nclient_keys = posthog.get_feature_flag_keys_by_evaluation_runtime(\n FeatureFlagEvaluationRuntime.CLIENT\n)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user, preserving valid serialized JSON.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Optional[str]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team'). Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and end the consumer threads. Do not use directly, call `shutdown()` instead. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss. Normally this method blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Queued spans get one final flush of up to 30 s (plus a request already in flight); any it cannot send are discarded with a warning, as are spans still open. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. When called directly from an SDK callback such as ``on_error``, shutdown is deferred to avoid blocking the worker that invoked the callback. If the callback must coordinate a blocking shutdown, have it signal an application-owned thread and return before that thread calls shutdown. Do not wait inside the callback for another thread or task that calls a lifecycle method.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span. A forked child starts with no active span; pass the parent span to continue a trace across a fork.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog = Posthog(\"\", traces={\"service_name\": \"checkout-api\"})\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is delivered on an isolated queue with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name, normally one of the `$ai_*` event names. **kwargs: Same optional arguments as `capture()`.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import capture_ai\n\nuuid = capture_ai(\n \"$ai_generation\",\n distinct_id=\"user_123\",\n properties={\"$ai_model\": \"gpt-5\"},\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip. Overriding reserved exception properties through ``properties`` is deprecated and will stop working in the next major version.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation and omit flags that cannot be evaluated locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is ``True``. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "Reads the `evaluation_runtime` each flag definition carries, so no extra request is made. Returns `None` when local evaluation has not loaded a definition for this key. A definition that carries no runtime reports `FeatureFlagEvaluationRuntime.ALL`, the default PostHog applies.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_evaluation_runtime\nruntime = get_feature_flag_evaluation_runtime(\"my-flag\")" - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate.", - "details": "A flag set to `FeatureFlagEvaluationRuntime.ALL` suits either runtime, so it is returned for `CLIENT` and for `SERVER`. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_keys_by_evaluation_runtime\nclient_keys = get_feature_flag_keys_by_evaluation_runtime(FeatureFlagEvaluationRuntime.CLIENT)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and stop the client's background workers. Use `shutdown()` directly in most cases. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. This normally blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. Calls made directly from SDK callbacks such as ``on_error`` are deferred to avoid deadlocking the worker. If blocking completion is required, signal an application-owned thread, return from the callback, and call ``shutdown()`` from that thread. Do not wait inside a callback for another thread or task calling a lifecycle method.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "import posthog\nposthog.traces = {\"service_name\": \"checkout-api\"}\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Tracing", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.70.1.json b/references/posthog-python-references-7.70.1.json deleted file mode 100644 index affb9655a..000000000 --- a/references/posthog-python-references-7.70.1.json +++ /dev/null @@ -1,3548 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.70.1", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "enable_full_ai_capture", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_trace_context", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "traces", - "description": "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.", - "isOptional": true, - "type": "dict" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to. Falls back to the context distinct ID; the call is dropped with a warning if neither is available.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is queued on an isolated AI lane with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is True. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely. Queued spans are sent at the same time, within the same", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nruntime = posthog.get_feature_flag_evaluation_runtime(\"my-flag\")\nif runtime is FeatureFlagEvaluationRuntime.SERVER:\n ..." - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate. A flag set to ``FeatureFlagEvaluationRuntime.ALL`` suits either runtime, so it is returned for ``CLIENT`` and for ``SERVER``, and asking for ``ALL`` returns every loaded flag. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "The runtime to match, as a ``FeatureFlagEvaluationRuntime`` or its string value.", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nclient_keys = posthog.get_feature_flag_keys_by_evaluation_runtime(\n FeatureFlagEvaluationRuntime.CLIENT\n)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user, preserving valid serialized JSON.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Optional[str]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team'). Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and end the consumer threads. Do not use directly, call `shutdown()` instead. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss. Normally this method blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Queued spans get one final flush of up to 30 s (plus a request already in flight); any it cannot send are discarded with a warning, as are spans still open. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. When called directly from an SDK callback such as ``on_error``, shutdown is deferred to avoid blocking the worker that invoked the callback. If the callback must coordinate a blocking shutdown, have it signal an application-owned thread and return before that thread calls shutdown. Do not wait inside the callback for another thread or task that calls a lifecycle method.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span. A forked child starts with no active span; pass the parent span to continue a trace across a fork.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog = Posthog(\"\", traces={\"service_name\": \"checkout-api\"})\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is delivered on an isolated queue with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name, normally one of the `$ai_*` event names. **kwargs: Same optional arguments as `capture()`.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import capture_ai\n\nuuid = capture_ai(\n \"$ai_generation\",\n distinct_id=\"user_123\",\n properties={\"$ai_model\": \"gpt-5\"},\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip. Overriding reserved exception properties through ``properties`` is deprecated and will stop working in the next major version.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation and omit flags that cannot be evaluated locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is ``True``. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "Reads the `evaluation_runtime` each flag definition carries, so no extra request is made. Returns `None` when local evaluation has not loaded a definition for this key. A definition that carries no runtime reports `FeatureFlagEvaluationRuntime.ALL`, the default PostHog applies.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_evaluation_runtime\nruntime = get_feature_flag_evaluation_runtime(\"my-flag\")" - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate.", - "details": "A flag set to `FeatureFlagEvaluationRuntime.ALL` suits either runtime, so it is returned for `CLIENT` and for `SERVER`. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_keys_by_evaluation_runtime\nclient_keys = get_feature_flag_keys_by_evaluation_runtime(FeatureFlagEvaluationRuntime.CLIENT)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and stop the client's background workers. Use `shutdown()` directly in most cases. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. This normally blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. Calls made directly from SDK callbacks such as ``on_error`` are deferred to avoid deadlocking the worker. If blocking completion is required, signal an application-owned thread, return from the callback, and call ``shutdown()`` from that thread. Do not wait inside a callback for another thread or task calling a lifecycle method.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "import posthog\nposthog.traces = {\"service_name\": \"checkout-api\"}\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Tracing", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.70.2.json b/references/posthog-python-references-7.70.2.json deleted file mode 100644 index 598946836..000000000 --- a/references/posthog-python-references-7.70.2.json +++ /dev/null @@ -1,3548 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.70.2", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "enable_full_ai_capture", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_trace_context", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "traces", - "description": "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.", - "isOptional": true, - "type": "dict" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to. Falls back to the context distinct ID; the call is dropped with a warning if neither is available.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is queued on an isolated AI lane with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is True. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Force a flush from the internal queue to the server. Do not use directly, call `shutdown()` instead.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely. Queued spans are sent at the same time, within the same", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name')\nposthog.flush() # Ensures the event is sent immediately" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nruntime = posthog.get_feature_flag_evaluation_runtime(\"my-flag\")\nif runtime is FeatureFlagEvaluationRuntime.SERVER:\n ..." - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate. A flag set to ``FeatureFlagEvaluationRuntime.ALL`` suits either runtime, so it is returned for ``CLIENT`` and for ``SERVER``, and asking for ``ALL`` returns every loaded flag. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "The runtime to match, as a ``FeatureFlagEvaluationRuntime`` or its string value.", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nclient_keys = posthog.get_feature_flag_keys_by_evaluation_runtime(\n FeatureFlagEvaluationRuntime.CLIENT\n)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user, preserving valid serialized JSON.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Optional[str]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team'). Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and end the consumer threads. Do not use directly, call `shutdown()` instead. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. Call this before the process ends in serverless environments to avoid data loss. Normally this method blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Queued spans get one final flush of up to 30 s (plus a request already in flight); any it cannot send are discarded with a warning, as are spans still open. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. When called directly from an SDK callback such as ``on_error``, shutdown is deferred to avoid blocking the worker that invoked the callback. If the callback must coordinate a blocking shutdown, have it signal an application-owned thread and return before that thread calls shutdown. Do not wait inside the callback for another thread or task that calls a lifecycle method.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span. A forked child starts with no active span; pass the parent span to continue a trace across a fork.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog = Posthog(\"\", traces={\"service_name\": \"checkout-api\"})\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is delivered on an isolated queue with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name, normally one of the `$ai_*` event names. **kwargs: Same optional arguments as `capture()`.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import capture_ai\n\nuuid = capture_ai(\n \"$ai_generation\",\n distinct_id=\"user_123\",\n properties={\"$ai_model\": \"gpt-5\"},\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip. Overriding reserved exception properties through ``properties`` is deprecated and will stop working in the next major version.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation and omit flags that cannot be evaluated locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is ``True``. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Tell the client to flush all queued events.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Maximum seconds to wait for the queue to flush. Defaults to 10 seconds. Pass ``None`` to wait indefinitely.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import flush\nflush()" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "Reads the `evaluation_runtime` each flag definition carries, so no extra request is made. Returns `None` when local evaluation has not loaded a definition for this key. A definition that carries no runtime reports `FeatureFlagEvaluationRuntime.ALL`, the default PostHog applies.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_evaluation_runtime\nruntime = get_feature_flag_evaluation_runtime(\"my-flag\")" - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate.", - "details": "A flag set to `FeatureFlagEvaluationRuntime.ALL` suits either runtime, so it is returned for `CLIENT` and for `SERVER`. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_keys_by_evaluation_runtime\nclient_keys = get_feature_flag_keys_by_evaluation_runtime(FeatureFlagEvaluationRuntime.CLIENT)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and stop the client's background workers. Use `shutdown()` directly in most cases. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Flush all messages and cleanly shutdown the client. This normally blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. Calls made directly from SDK callbacks such as ``on_error`` are deferred to avoid deadlocking the worker. If blocking completion is required, signal an application-owned thread, return from the callback, and call ``shutdown()`` from that thread. Do not wait inside a callback for another thread or task calling a lifecycle method.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "import posthog\nposthog.traces = {\"service_name\": \"checkout-api\"}\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Tracing", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.72.0.json b/references/posthog-python-references-7.72.0.json deleted file mode 100644 index 05421adfc..000000000 --- a/references/posthog-python-references-7.72.0.json +++ /dev/null @@ -1,3548 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.72.0", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "enable_full_ai_capture", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_trace_context", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "traces", - "description": "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.", - "isOptional": true, - "type": "dict" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to. Falls back to the context distinct ID; the call is dropped with a warning if neither is available.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is queued on an isolated AI lane with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is True. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Attempt immediate delivery of queued events and ended spans, keeping the client reusable. For a client shared across requests or serverless invocations (including the module-level client), call ``flush()`` before a short-lived invocation returns. Use ``shutdown()`` instead only for final process cleanup or when disposing of a client that will not be reused. Flush does not stop the background workers or feature flag poller, and does not end open spans. Returning does not guarantee server receipt: pending work can remain after a timeout or span export failure, and failed events may be dropped by the consumers. Calls made directly from SDK callbacks such as ``on_error`` are deferred rather than blocking the worker that invoked the callback.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Seconds to wait for event queues to drain, shared across event lanes. Defaults to 10 seconds. Pass ``None`` to wait without a time limit; this does not guarantee successful delivery. Queued spans flush concurrently. The span exporter waits up to this many seconds for an in-flight flush, then uses a fresh drain budget once it acquires the lock. If the lock wait times out, the in-flight flush is left to finish. At least one span request is attempted after acquiring the lock, even with no budget left; retriable failures are retried after backoff while budget remains, with one last attempt at the deadline. Each span request is bounded by the client's ``timeout`` in seconds, and the last request is not cut short. This is therefore not a strict wall-clock limit for the whole call. With ``None``, a retriable span failure is left for a later flush rather than retried within this call.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name', distinct_id='user_id')\n# Before a serverless invocation returns; keep the shared client open.\nposthog.flush(timeout_seconds=10)" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nruntime = posthog.get_feature_flag_evaluation_runtime(\"my-flag\")\nif runtime is FeatureFlagEvaluationRuntime.SERVER:\n ..." - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate. A flag set to ``FeatureFlagEvaluationRuntime.ALL`` suits either runtime, so it is returned for ``CLIENT`` and for ``SERVER``, and asking for ``ALL`` returns every loaded flag. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "The runtime to match, as a ``FeatureFlagEvaluationRuntime`` or its string value.", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nclient_keys = posthog.get_feature_flag_keys_by_evaluation_runtime(\n FeatureFlagEvaluationRuntime.CLIENT\n)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user, preserving valid serialized JSON.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Optional[str]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team'). Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and end the consumer threads. Do not use directly, call `shutdown()` instead. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Attempt final delivery and permanently shut down the client. Call this for final process cleanup or when disposing of a client that will not be reused. It closes capture lanes, stops background workers and the feature flag poller, and tears down integrations. Do not call it at the end of each request or serverless invocation when the client is shared; call ``flush()`` before returning instead. A shut-down client cannot be reused; create a new client if needed. Normally this method blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Event draining has no timeout. Queued spans get one final flush with up to 30 seconds waiting for an in-flight flush, then a fresh 30-second drain budget; the last HTTP request is not cut short. Any spans it cannot send are discarded with a warning, as are spans still open. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. When called directly from an SDK callback such as ``on_error``, shutdown is deferred to avoid blocking the worker that invoked the callback. If the callback must coordinate a blocking shutdown, have it signal an application-owned thread and return before that thread calls shutdown. Do not wait inside the callback for another thread or task that calls a lifecycle method.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span. A forked child starts with no active span; pass the parent span to continue a trace across a fork.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog = Posthog(\"\", traces={\"service_name\": \"checkout-api\"})\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is delivered on an isolated queue with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name, normally one of the `$ai_*` event names. **kwargs: Same optional arguments as `capture()`.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import capture_ai\n\nuuid = capture_ai(\n \"$ai_generation\",\n distinct_id=\"user_123\",\n properties={\"$ai_model\": \"gpt-5\"},\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip. Overriding reserved exception properties through ``properties`` is deprecated and will stop working in the next major version.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation and omit flags that cannot be evaluated locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is ``True``. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Attempt immediate delivery of queued events and ended spans, keeping the global client reusable. Call ``flush()`` before a short-lived request or serverless invocation returns when using the shared module-level client. Use ``shutdown()`` only for final process cleanup or a client that will not be reused. Flush does not stop the background workers or feature flag poller, and does not end open spans. Returning does not guarantee server receipt: pending work can remain after a timeout or span export failure, and failed events may be dropped by consumers. Calls made directly from SDK callbacks such as ``on_error`` are deferred rather than blocking the worker that invoked the callback.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Seconds to wait for event queues to drain, shared across event lanes. Defaults to 10 seconds. Pass ``None`` to wait without a time limit; this does not guarantee successful delivery. Queued spans flush concurrently, waiting up to this many seconds for an in-flight flush before starting a fresh drain budget. A lock wait timeout leaves the in-flight flush to finish. At least one span request is attempted after acquiring the lock, even with no budget left; retriable failures are retried after backoff while budget remains, with one last attempt at the deadline. The last span request is not cut short and is bounded by the client's ``timeout`` in seconds, so this is not a strict wall-clock limit for the whole call. With ``None``, a retriable span failure is left for a later flush rather than retried within this call.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "import posthog\nposthog.capture('event_name', distinct_id='user_id')\n# Before a serverless invocation returns; keep the global client open.\nposthog.flush(timeout_seconds=10)" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "Reads the `evaluation_runtime` each flag definition carries, so no extra request is made. Returns `None` when local evaluation has not loaded a definition for this key. A definition that carries no runtime reports `FeatureFlagEvaluationRuntime.ALL`, the default PostHog applies.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_evaluation_runtime\nruntime = get_feature_flag_evaluation_runtime(\"my-flag\")" - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate.", - "details": "A flag set to `FeatureFlagEvaluationRuntime.ALL` suits either runtime, so it is returned for `CLIENT` and for `SERVER`. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_keys_by_evaluation_runtime\nclient_keys = get_feature_flag_keys_by_evaluation_runtime(FeatureFlagEvaluationRuntime.CLIENT)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and stop the client's background workers. Use `shutdown()` directly in most cases. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Attempt final delivery and permanently shut down the global client. Call this for final process cleanup, not at the end of each request or serverless invocation that shares the module-level client. Use ``flush()`` before returning from those invocations instead. Shutdown closes capture lanes, stops background workers and the feature flag poller, and tears down integrations. The global client is not recreated automatically after shutdown. This normally blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Event draining has no timeout. Queued spans get a final flush with up to 30 seconds waiting for an in-flight flush, then a fresh 30-second drain budget; the last HTTP request is not cut short. Unsent queued spans and still-open spans are discarded with a warning. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. Calls made directly from SDK callbacks such as ``on_error`` are deferred to avoid deadlocking the worker. If blocking completion is required, signal an application-owned thread, return from the callback, and call ``shutdown()`` from that thread. Do not wait inside a callback for another thread or task calling a lifecycle method.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "import posthog\nposthog.traces = {\"service_name\": \"checkout-api\"}\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Tracing", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.73.0.json b/references/posthog-python-references-7.73.0.json deleted file mode 100644 index 9e6844b34..000000000 --- a/references/posthog-python-references-7.73.0.json +++ /dev/null @@ -1,3548 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.73.0", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "enable_full_ai_capture", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_trace_context", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "traces", - "description": "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.", - "isOptional": true, - "type": "dict" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to. Falls back to the context distinct ID; the call is dropped with a warning if neither is available.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is queued on an isolated AI lane with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is True. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Attempt immediate delivery of queued events and ended spans, keeping the client reusable. For a client shared across requests or serverless invocations (including the module-level client), call ``flush()`` before a short-lived invocation returns. Use ``shutdown()`` instead only for final process cleanup or when disposing of a client that will not be reused. Flush does not stop the background workers or feature flag poller, and does not end open spans. Returning does not guarantee server receipt: pending work can remain after a timeout or span export failure, and failed events may be dropped by the consumers. Calls made directly from SDK callbacks such as ``on_error`` are deferred rather than blocking the worker that invoked the callback.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Seconds to wait for event queues to drain, shared across event lanes. Defaults to 10 seconds. Pass ``None`` to wait without a time limit; this does not guarantee successful delivery. Queued spans flush concurrently. The span exporter waits up to this many seconds for an in-flight flush, then uses a fresh drain budget once it acquires the lock. If the lock wait times out, the in-flight flush is left to finish. At least one span request is attempted after acquiring the lock, even with no budget left; retriable failures are retried after backoff while budget remains, with one last attempt at the deadline. Each span request is bounded by the client's ``timeout`` in seconds, and the last request is not cut short. This is therefore not a strict wall-clock limit for the whole call. With ``None``, a retriable span failure is left for a later flush rather than retried within this call.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name', distinct_id='user_id')\n# Before a serverless invocation returns; keep the shared client open.\nposthog.flush(timeout_seconds=10)" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nruntime = posthog.get_feature_flag_evaluation_runtime(\"my-flag\")\nif runtime is FeatureFlagEvaluationRuntime.SERVER:\n ..." - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate. A flag set to ``FeatureFlagEvaluationRuntime.ALL`` suits either runtime, so it is returned for ``CLIENT`` and for ``SERVER``, and asking for ``ALL`` returns every loaded flag. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "The runtime to match, as a ``FeatureFlagEvaluationRuntime`` or its string value.", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nclient_keys = posthog.get_feature_flag_keys_by_evaluation_runtime(\n FeatureFlagEvaluationRuntime.CLIENT\n)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user, preserving valid serialized JSON.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Optional[str]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team'). Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and end the consumer threads. Do not use directly, call `shutdown()` instead. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Attempt final delivery and permanently shut down the client. Call this for final process cleanup or when disposing of a client that will not be reused. It closes capture lanes, stops background workers and the feature flag poller, and tears down integrations. Do not call it at the end of each request or serverless invocation when the client is shared; call ``flush()`` before returning instead. A shut-down client cannot be reused; create a new client if needed. Normally this method blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Event draining has no timeout. Queued spans get one final flush with up to 30 seconds waiting for an in-flight flush, then a fresh 30-second drain budget; the last HTTP request is not cut short. Any spans it cannot send are discarded with a warning, as are spans still open. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. When called directly from an SDK callback such as ``on_error``, shutdown is deferred to avoid blocking the worker that invoked the callback. If the callback must coordinate a blocking shutdown, have it signal an application-owned thread and return before that thread calls shutdown. Do not wait inside the callback for another thread or task that calls a lifecycle method.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span. A forked child starts with no active span; pass the parent span to continue a trace across a fork.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog = Posthog(\"\", traces={\"service_name\": \"checkout-api\"})\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is delivered on an isolated queue with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name, normally one of the `$ai_*` event names. **kwargs: Same optional arguments as `capture()`.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import capture_ai\n\nuuid = capture_ai(\n \"$ai_generation\",\n distinct_id=\"user_123\",\n properties={\"$ai_model\": \"gpt-5\"},\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip. Overriding reserved exception properties through ``properties`` is deprecated and will stop working in the next major version.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation and omit flags that cannot be evaluated locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is ``True``. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Attempt immediate delivery of queued events and ended spans, keeping the global client reusable. Call ``flush()`` before a short-lived request or serverless invocation returns when using the shared module-level client. Use ``shutdown()`` only for final process cleanup or a client that will not be reused. Flush does not stop the background workers or feature flag poller, and does not end open spans. Returning does not guarantee server receipt: pending work can remain after a timeout or span export failure, and failed events may be dropped by consumers. Calls made directly from SDK callbacks such as ``on_error`` are deferred rather than blocking the worker that invoked the callback.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Seconds to wait for event queues to drain, shared across event lanes. Defaults to 10 seconds. Pass ``None`` to wait without a time limit; this does not guarantee successful delivery. Queued spans flush concurrently, waiting up to this many seconds for an in-flight flush before starting a fresh drain budget. A lock wait timeout leaves the in-flight flush to finish. At least one span request is attempted after acquiring the lock, even with no budget left; retriable failures are retried after backoff while budget remains, with one last attempt at the deadline. The last span request is not cut short and is bounded by the client's ``timeout`` in seconds, so this is not a strict wall-clock limit for the whole call. With ``None``, a retriable span failure is left for a later flush rather than retried within this call.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "import posthog\nposthog.capture('event_name', distinct_id='user_id')\n# Before a serverless invocation returns; keep the global client open.\nposthog.flush(timeout_seconds=10)" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "Reads the `evaluation_runtime` each flag definition carries, so no extra request is made. Returns `None` when local evaluation has not loaded a definition for this key. A definition that carries no runtime reports `FeatureFlagEvaluationRuntime.ALL`, the default PostHog applies.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_evaluation_runtime\nruntime = get_feature_flag_evaluation_runtime(\"my-flag\")" - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate.", - "details": "A flag set to `FeatureFlagEvaluationRuntime.ALL` suits either runtime, so it is returned for `CLIENT` and for `SERVER`. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_keys_by_evaluation_runtime\nclient_keys = get_feature_flag_keys_by_evaluation_runtime(FeatureFlagEvaluationRuntime.CLIENT)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and stop the client's background workers. Use `shutdown()` directly in most cases. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Attempt final delivery and permanently shut down the global client. Call this for final process cleanup, not at the end of each request or serverless invocation that shares the module-level client. Use ``flush()`` before returning from those invocations instead. Shutdown closes capture lanes, stops background workers and the feature flag poller, and tears down integrations. The global client is not recreated automatically after shutdown. This normally blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Event draining has no timeout. Queued spans get a final flush with up to 30 seconds waiting for an in-flight flush, then a fresh 30-second drain budget; the last HTTP request is not cut short. Unsent queued spans and still-open spans are discarded with a warning. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. Calls made directly from SDK callbacks such as ``on_error`` are deferred to avoid deadlocking the worker. If blocking completion is required, signal an application-owned thread, return from the callback, and call ``shutdown()`` from that thread. Do not wait inside a callback for another thread or task calling a lifecycle method.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "import posthog\nposthog.traces = {\"service_name\": \"checkout-api\"}\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Tracing", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.73.1.json b/references/posthog-python-references-7.73.1.json deleted file mode 100644 index 9c588f586..000000000 --- a/references/posthog-python-references-7.73.1.json +++ /dev/null @@ -1,3548 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.73.1", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "enable_full_ai_capture", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_trace_context", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "traces", - "description": "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.", - "isOptional": true, - "type": "dict" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to. Falls back to the context distinct ID; the call is dropped with a warning if neither is available.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is queued on an isolated AI lane with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is True. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Attempt immediate delivery of queued events and ended spans, keeping the client reusable. For a client shared across requests or serverless invocations (including the module-level client), call ``flush()`` before a short-lived invocation returns. Use ``shutdown()`` instead only for final process cleanup or when disposing of a client that will not be reused. Flush does not stop the background workers or feature flag poller, and does not end open spans. Returning does not guarantee server receipt: pending work can remain after a timeout or span export failure, and failed events may be dropped by the consumers. Calls made directly from SDK callbacks such as ``on_error`` are deferred rather than blocking the worker that invoked the callback.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Seconds to wait for event queues to drain, shared across event lanes. Defaults to 10 seconds. Pass ``None`` to wait without a time limit; this does not guarantee successful delivery. Queued spans flush concurrently. The span exporter waits up to this many seconds for an in-flight flush, then uses a fresh drain budget once it acquires the lock. If the lock wait times out, the in-flight flush is left to finish. At least one span request is attempted after acquiring the lock, even with no budget left; retriable failures are retried after backoff while budget remains, with one last attempt at the deadline. Each span request is bounded by the client's ``timeout`` in seconds, and the last request is not cut short. This is therefore not a strict wall-clock limit for the whole call. With ``None``, a retriable span failure is left for a later flush rather than retried within this call.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name', distinct_id='user_id')\n# Before a serverless invocation returns; keep the shared client open.\nposthog.flush(timeout_seconds=10)" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nruntime = posthog.get_feature_flag_evaluation_runtime(\"my-flag\")\nif runtime is FeatureFlagEvaluationRuntime.SERVER:\n ..." - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate. A flag set to ``FeatureFlagEvaluationRuntime.ALL`` suits either runtime, so it is returned for ``CLIENT`` and for ``SERVER``, and asking for ``ALL`` returns every loaded flag. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "The runtime to match, as a ``FeatureFlagEvaluationRuntime`` or its string value.", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nclient_keys = posthog.get_feature_flag_keys_by_evaluation_runtime(\n FeatureFlagEvaluationRuntime.CLIENT\n)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user, preserving valid serialized JSON.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Optional[str]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team'). Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and end the consumer threads. Do not use directly, call `shutdown()` instead. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Attempt final delivery and permanently shut down the client. Call this for final process cleanup or when disposing of a client that will not be reused. It closes capture lanes, stops background workers and the feature flag poller, and tears down integrations. Do not call it at the end of each request or serverless invocation when the client is shared; call ``flush()`` before returning instead. A shut-down client cannot be reused; create a new client if needed. Normally this method blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Event draining has no timeout. Queued spans get one final flush with up to 30 seconds waiting for an in-flight flush, then a fresh 30-second drain budget; the last HTTP request is not cut short. Any spans it cannot send are discarded with a warning, as are spans still open. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. When called directly from an SDK callback such as ``on_error``, shutdown is deferred to avoid blocking the worker that invoked the callback. If the callback must coordinate a blocking shutdown, have it signal an application-owned thread and return before that thread calls shutdown. Do not wait inside the callback for another thread or task that calls a lifecycle method.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span. A forked child starts with no active span; pass the parent span to continue a trace across a fork.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog = Posthog(\"\", traces={\"service_name\": \"checkout-api\"})\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is delivered on an isolated queue with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name, normally one of the `$ai_*` event names. **kwargs: Same optional arguments as `capture()`.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import capture_ai\n\nuuid = capture_ai(\n \"$ai_generation\",\n distinct_id=\"user_123\",\n properties={\"$ai_model\": \"gpt-5\"},\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip. Overriding reserved exception properties through ``properties`` is deprecated and will stop working in the next major version.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation and omit flags that cannot be evaluated locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is ``True``. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Attempt immediate delivery of queued events and ended spans, keeping the global client reusable. Call ``flush()`` before a short-lived request or serverless invocation returns when using the shared module-level client. Use ``shutdown()`` only for final process cleanup or a client that will not be reused. Flush does not stop the background workers or feature flag poller, and does not end open spans. Returning does not guarantee server receipt: pending work can remain after a timeout or span export failure, and failed events may be dropped by consumers. Calls made directly from SDK callbacks such as ``on_error`` are deferred rather than blocking the worker that invoked the callback.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Seconds to wait for event queues to drain, shared across event lanes. Defaults to 10 seconds. Pass ``None`` to wait without a time limit; this does not guarantee successful delivery. Queued spans flush concurrently, waiting up to this many seconds for an in-flight flush before starting a fresh drain budget. A lock wait timeout leaves the in-flight flush to finish. At least one span request is attempted after acquiring the lock, even with no budget left; retriable failures are retried after backoff while budget remains, with one last attempt at the deadline. The last span request is not cut short and is bounded by the client's ``timeout`` in seconds, so this is not a strict wall-clock limit for the whole call. With ``None``, a retriable span failure is left for a later flush rather than retried within this call.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "import posthog\nposthog.capture('event_name', distinct_id='user_id')\n# Before a serverless invocation returns; keep the global client open.\nposthog.flush(timeout_seconds=10)" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "Reads the `evaluation_runtime` each flag definition carries, so no extra request is made. Returns `None` when local evaluation has not loaded a definition for this key. A definition that carries no runtime reports `FeatureFlagEvaluationRuntime.ALL`, the default PostHog applies.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_evaluation_runtime\nruntime = get_feature_flag_evaluation_runtime(\"my-flag\")" - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate.", - "details": "A flag set to `FeatureFlagEvaluationRuntime.ALL` suits either runtime, so it is returned for `CLIENT` and for `SERVER`. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_keys_by_evaluation_runtime\nclient_keys = get_feature_flag_keys_by_evaluation_runtime(FeatureFlagEvaluationRuntime.CLIENT)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and stop the client's background workers. Use `shutdown()` directly in most cases. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Attempt final delivery and permanently shut down the global client. Call this for final process cleanup, not at the end of each request or serverless invocation that shares the module-level client. Use ``flush()`` before returning from those invocations instead. Shutdown closes capture lanes, stops background workers and the feature flag poller, and tears down integrations. The global client is not recreated automatically after shutdown. This normally blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Event draining has no timeout. Queued spans get a final flush with up to 30 seconds waiting for an in-flight flush, then a fresh 30-second drain budget; the last HTTP request is not cut short. Unsent queued spans and still-open spans are discarded with a warning. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. Calls made directly from SDK callbacks such as ``on_error`` are deferred to avoid deadlocking the worker. If blocking completion is required, signal an application-owned thread, return from the callback, and call ``shutdown()`` from that thread. Do not wait inside a callback for another thread or task calling a lifecycle method.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "import posthog\nposthog.traces = {\"service_name\": \"checkout-api\"}\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Tracing", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.73.2.json b/references/posthog-python-references-7.73.2.json deleted file mode 100644 index 0df272044..000000000 --- a/references/posthog-python-references-7.73.2.json +++ /dev/null @@ -1,3548 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.73.2", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "enable_full_ai_capture", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_trace_context", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "traces", - "description": "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.", - "isOptional": true, - "type": "dict" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to. Falls back to the context distinct ID; the call is dropped with a warning if neither is available.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is queued on an isolated AI lane with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is True. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Attempt immediate delivery of queued events and ended spans, keeping the client reusable. For a client shared across requests or serverless invocations (including the module-level client), call ``flush()`` before a short-lived invocation returns. Use ``shutdown()`` instead only for final process cleanup or when disposing of a client that will not be reused. Flush does not stop the background workers or feature flag poller, and does not end open spans. Returning does not guarantee server receipt: pending work can remain after a timeout or span export failure, and failed events may be dropped by the consumers. Calls made directly from SDK callbacks such as ``on_error`` are deferred rather than blocking the worker that invoked the callback.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Seconds to wait for event queues to drain, shared across event lanes. Defaults to 10 seconds. Pass ``None`` to wait without a time limit; this does not guarantee successful delivery. Queued spans flush concurrently. The span exporter waits up to this many seconds for an in-flight flush, then uses a fresh drain budget once it acquires the lock. If the lock wait times out, the in-flight flush is left to finish. At least one span request is attempted after acquiring the lock, even with no budget left; retriable failures are retried after backoff while budget remains, with one last attempt at the deadline. Each span request is bounded by the client's ``timeout`` in seconds, and the last request is not cut short. This is therefore not a strict wall-clock limit for the whole call. With ``None``, a retriable span failure is left for a later flush rather than retried within this call.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name', distinct_id='user_id')\n# Before a serverless invocation returns; keep the shared client open.\nposthog.flush(timeout_seconds=10)" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nruntime = posthog.get_feature_flag_evaluation_runtime(\"my-flag\")\nif runtime is FeatureFlagEvaluationRuntime.SERVER:\n ..." - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate. A flag set to ``FeatureFlagEvaluationRuntime.ALL`` suits either runtime, so it is returned for ``CLIENT`` and for ``SERVER``, and asking for ``ALL`` returns every loaded flag. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "The runtime to match, as a ``FeatureFlagEvaluationRuntime`` or its string value.", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nclient_keys = posthog.get_feature_flag_keys_by_evaluation_runtime(\n FeatureFlagEvaluationRuntime.CLIENT\n)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user, preserving valid serialized JSON.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Optional[str]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team'). Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and end the consumer threads. Do not use directly, call `shutdown()` instead. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Attempt final delivery and permanently shut down the client. Call this for final process cleanup or when disposing of a client that will not be reused. It closes capture lanes, stops background workers and the feature flag poller, and tears down integrations. Do not call it at the end of each request or serverless invocation when the client is shared; call ``flush()`` before returning instead. A shut-down client cannot be reused; create a new client if needed. Normally this method blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Event draining has no timeout. Queued spans get one final flush with up to 30 seconds waiting for an in-flight flush, then a fresh 30-second drain budget; the last HTTP request is not cut short. Any spans it cannot send are discarded with a warning, as are spans still open. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. When called directly from an SDK callback such as ``on_error``, shutdown is deferred to avoid blocking the worker that invoked the callback. If the callback must coordinate a blocking shutdown, have it signal an application-owned thread and return before that thread calls shutdown. Do not wait inside the callback for another thread or task that calls a lifecycle method.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span. A forked child starts with no active span; pass the parent span to continue a trace across a fork.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog = Posthog(\"\", traces={\"service_name\": \"checkout-api\"})\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is delivered on an isolated queue with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name, normally one of the `$ai_*` event names. **kwargs: Same optional arguments as `capture()`.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import capture_ai\n\nuuid = capture_ai(\n \"$ai_generation\",\n distinct_id=\"user_123\",\n properties={\"$ai_model\": \"gpt-5\"},\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip. Overriding reserved exception properties through ``properties`` is deprecated and will stop working in the next major version.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation and omit flags that cannot be evaluated locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is ``True``. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Attempt immediate delivery of queued events and ended spans, keeping the global client reusable. Call ``flush()`` before a short-lived request or serverless invocation returns when using the shared module-level client. Use ``shutdown()`` only for final process cleanup or a client that will not be reused. Flush does not stop the background workers or feature flag poller, and does not end open spans. Returning does not guarantee server receipt: pending work can remain after a timeout or span export failure, and failed events may be dropped by consumers. Calls made directly from SDK callbacks such as ``on_error`` are deferred rather than blocking the worker that invoked the callback.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Seconds to wait for event queues to drain, shared across event lanes. Defaults to 10 seconds. Pass ``None`` to wait without a time limit; this does not guarantee successful delivery. Queued spans flush concurrently, waiting up to this many seconds for an in-flight flush before starting a fresh drain budget. A lock wait timeout leaves the in-flight flush to finish. At least one span request is attempted after acquiring the lock, even with no budget left; retriable failures are retried after backoff while budget remains, with one last attempt at the deadline. The last span request is not cut short and is bounded by the client's ``timeout`` in seconds, so this is not a strict wall-clock limit for the whole call. With ``None``, a retriable span failure is left for a later flush rather than retried within this call.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "import posthog\nposthog.capture('event_name', distinct_id='user_id')\n# Before a serverless invocation returns; keep the global client open.\nposthog.flush(timeout_seconds=10)" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "Reads the `evaluation_runtime` each flag definition carries, so no extra request is made. Returns `None` when local evaluation has not loaded a definition for this key. A definition that carries no runtime reports `FeatureFlagEvaluationRuntime.ALL`, the default PostHog applies.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_evaluation_runtime\nruntime = get_feature_flag_evaluation_runtime(\"my-flag\")" - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate.", - "details": "A flag set to `FeatureFlagEvaluationRuntime.ALL` suits either runtime, so it is returned for `CLIENT` and for `SERVER`. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_keys_by_evaluation_runtime\nclient_keys = get_feature_flag_keys_by_evaluation_runtime(FeatureFlagEvaluationRuntime.CLIENT)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and stop the client's background workers. Use `shutdown()` directly in most cases. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Attempt final delivery and permanently shut down the global client. Call this for final process cleanup, not at the end of each request or serverless invocation that shares the module-level client. Use ``flush()`` before returning from those invocations instead. Shutdown closes capture lanes, stops background workers and the feature flag poller, and tears down integrations. The global client is not recreated automatically after shutdown. This normally blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Event draining has no timeout. Queued spans get a final flush with up to 30 seconds waiting for an in-flight flush, then a fresh 30-second drain budget; the last HTTP request is not cut short. Unsent queued spans and still-open spans are discarded with a warning. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. Calls made directly from SDK callbacks such as ``on_error`` are deferred to avoid deadlocking the worker. If blocking completion is required, signal an application-owned thread, return from the callback, and call ``shutdown()`` from that thread. Do not wait inside a callback for another thread or task calling a lifecycle method.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "import posthog\nposthog.traces = {\"service_name\": \"checkout-api\"}\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Tracing", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.73.3.json b/references/posthog-python-references-7.73.3.json deleted file mode 100644 index 973a24408..000000000 --- a/references/posthog-python-references-7.73.3.json +++ /dev/null @@ -1,3548 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.73.3", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "enable_full_ai_capture", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_trace_context", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "traces", - "description": "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.", - "isOptional": true, - "type": "dict" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to. Falls back to the context distinct ID; the call is dropped with a warning if neither is available.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is queued on an isolated AI lane with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is True. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Attempt immediate delivery of queued events and ended spans, keeping the client reusable. For a client shared across requests or serverless invocations (including the module-level client), call ``flush()`` before a short-lived invocation returns. Use ``shutdown()`` instead only for final process cleanup or when disposing of a client that will not be reused. Flush does not stop the background workers or feature flag poller, and does not end open spans. Returning does not guarantee server receipt: pending work can remain after a timeout or span export failure, and failed events may be dropped by the consumers. Calls made directly from SDK callbacks such as ``on_error`` are deferred rather than blocking the worker that invoked the callback.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Seconds to wait for event queues to drain, shared across event lanes. Defaults to 10 seconds. Pass ``None`` to wait without a time limit; this does not guarantee successful delivery. Queued spans flush concurrently. The span exporter waits up to this many seconds for an in-flight flush, then uses a fresh drain budget once it acquires the lock. If the lock wait times out, the in-flight flush is left to finish. At least one span request is attempted after acquiring the lock, even with no budget left; retriable failures are retried after backoff while budget remains, with one last attempt at the deadline. Each span request is bounded by the client's ``timeout`` in seconds, and the last request is not cut short. This is therefore not a strict wall-clock limit for the whole call. With ``None``, a retriable span failure is left for a later flush rather than retried within this call.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name', distinct_id='user_id')\n# Before a serverless invocation returns; keep the shared client open.\nposthog.flush(timeout_seconds=10)" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nruntime = posthog.get_feature_flag_evaluation_runtime(\"my-flag\")\nif runtime is FeatureFlagEvaluationRuntime.SERVER:\n ..." - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate. A flag set to ``FeatureFlagEvaluationRuntime.ALL`` suits either runtime, so it is returned for ``CLIENT`` and for ``SERVER``, and asking for ``ALL`` returns every loaded flag. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "The runtime to match, as a ``FeatureFlagEvaluationRuntime`` or its string value.", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nclient_keys = posthog.get_feature_flag_keys_by_evaluation_runtime(\n FeatureFlagEvaluationRuntime.CLIENT\n)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user, preserving valid serialized JSON.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Optional[str]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team'). Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and end the consumer threads. Do not use directly, call `shutdown()` instead. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Attempt final delivery and permanently shut down the client. Call this for final process cleanup or when disposing of a client that will not be reused. It closes capture lanes, stops background workers and the feature flag poller, and tears down integrations. Do not call it at the end of each request or serverless invocation when the client is shared; call ``flush()`` before returning instead. A shut-down client cannot be reused; create a new client if needed. Normally this method blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Event draining has no timeout. Queued spans get one final flush with up to 30 seconds waiting for an in-flight flush, then a fresh 30-second drain budget; the last HTTP request is not cut short. Any spans it cannot send are discarded with a warning, as are spans still open. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. When called directly from an SDK callback such as ``on_error``, shutdown is deferred to avoid blocking the worker that invoked the callback. If the callback must coordinate a blocking shutdown, have it signal an application-owned thread and return before that thread calls shutdown. Do not wait inside the callback for another thread or task that calls a lifecycle method.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span. A forked child starts with no active span; pass the parent span to continue a trace across a fork.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog = Posthog(\"\", traces={\"service_name\": \"checkout-api\"})\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is delivered on an isolated queue with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name, normally one of the `$ai_*` event names. **kwargs: Same optional arguments as `capture()`.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import capture_ai\n\nuuid = capture_ai(\n \"$ai_generation\",\n distinct_id=\"user_123\",\n properties={\"$ai_model\": \"gpt-5\"},\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip. Overriding reserved exception properties through ``properties`` is deprecated and will stop working in the next major version.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation and omit flags that cannot be evaluated locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is ``True``. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Attempt immediate delivery of queued events and ended spans, keeping the global client reusable. Call ``flush()`` before a short-lived request or serverless invocation returns when using the shared module-level client. Use ``shutdown()`` only for final process cleanup or a client that will not be reused. Flush does not stop the background workers or feature flag poller, and does not end open spans. Returning does not guarantee server receipt: pending work can remain after a timeout or span export failure, and failed events may be dropped by consumers. Calls made directly from SDK callbacks such as ``on_error`` are deferred rather than blocking the worker that invoked the callback.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Seconds to wait for event queues to drain, shared across event lanes. Defaults to 10 seconds. Pass ``None`` to wait without a time limit; this does not guarantee successful delivery. Queued spans flush concurrently, waiting up to this many seconds for an in-flight flush before starting a fresh drain budget. A lock wait timeout leaves the in-flight flush to finish. At least one span request is attempted after acquiring the lock, even with no budget left; retriable failures are retried after backoff while budget remains, with one last attempt at the deadline. The last span request is not cut short and is bounded by the client's ``timeout`` in seconds, so this is not a strict wall-clock limit for the whole call. With ``None``, a retriable span failure is left for a later flush rather than retried within this call.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "import posthog\nposthog.capture('event_name', distinct_id='user_id')\n# Before a serverless invocation returns; keep the global client open.\nposthog.flush(timeout_seconds=10)" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "Reads the `evaluation_runtime` each flag definition carries, so no extra request is made. Returns `None` when local evaluation has not loaded a definition for this key. A definition that carries no runtime reports `FeatureFlagEvaluationRuntime.ALL`, the default PostHog applies.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_evaluation_runtime\nruntime = get_feature_flag_evaluation_runtime(\"my-flag\")" - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate.", - "details": "A flag set to `FeatureFlagEvaluationRuntime.ALL` suits either runtime, so it is returned for `CLIENT` and for `SERVER`. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_keys_by_evaluation_runtime\nclient_keys = get_feature_flag_keys_by_evaluation_runtime(FeatureFlagEvaluationRuntime.CLIENT)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and stop the client's background workers. Use `shutdown()` directly in most cases. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Attempt final delivery and permanently shut down the global client. Call this for final process cleanup, not at the end of each request or serverless invocation that shares the module-level client. Use ``flush()`` before returning from those invocations instead. Shutdown closes capture lanes, stops background workers and the feature flag poller, and tears down integrations. The global client is not recreated automatically after shutdown. This normally blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Event draining has no timeout. Queued spans get a final flush with up to 30 seconds waiting for an in-flight flush, then a fresh 30-second drain budget; the last HTTP request is not cut short. Unsent queued spans and still-open spans are discarded with a warning. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. Calls made directly from SDK callbacks such as ``on_error`` are deferred to avoid deadlocking the worker. If blocking completion is required, signal an application-owned thread, return from the callback, and call ``shutdown()`` from that thread. Do not wait inside a callback for another thread or task calling a lifecycle method.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "import posthog\nposthog.traces = {\"service_name\": \"checkout-api\"}\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Tracing", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.74.0.json b/references/posthog-python-references-7.74.0.json deleted file mode 100644 index 2053aac41..000000000 --- a/references/posthog-python-references-7.74.0.json +++ /dev/null @@ -1,3548 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.74.0", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "enable_full_ai_capture", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_trace_context", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "traces", - "description": "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.", - "isOptional": true, - "type": "dict" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to. Falls back to the context distinct ID; the call is dropped with a warning if neither is available.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is queued on an isolated AI lane with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is True. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Attempt immediate delivery of queued events and ended spans, keeping the client reusable. For a client shared across requests or serverless invocations (including the module-level client), call ``flush()`` before a short-lived invocation returns. Use ``shutdown()`` instead only for final process cleanup or when disposing of a client that will not be reused. Flush does not stop the background workers or feature flag poller, and does not end open spans. Returning does not guarantee server receipt: pending work can remain after a timeout or span export failure, and failed events may be dropped by the consumers. Calls made directly from SDK callbacks such as ``on_error`` are deferred rather than blocking the worker that invoked the callback.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Seconds to wait for event queues to drain, shared across event lanes. Defaults to 10 seconds. Pass ``None`` to wait without a time limit; this does not guarantee successful delivery. Queued spans flush concurrently. The span exporter waits up to this many seconds for an in-flight flush, then uses a fresh drain budget once it acquires the lock. If the lock wait times out, the in-flight flush is left to finish. At least one span request is attempted after acquiring the lock, even with no budget left; retriable failures are retried after backoff while budget remains, with one last attempt at the deadline. Each span request is bounded by the client's ``timeout`` in seconds, and the last request is not cut short. This is therefore not a strict wall-clock limit for the whole call. With ``None``, a retriable span failure is left for a later flush rather than retried within this call.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name', distinct_id='user_id')\n# Before a serverless invocation returns; keep the shared client open.\nposthog.flush(timeout_seconds=10)" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nruntime = posthog.get_feature_flag_evaluation_runtime(\"my-flag\")\nif runtime is FeatureFlagEvaluationRuntime.SERVER:\n ..." - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate. A flag set to ``FeatureFlagEvaluationRuntime.ALL`` suits either runtime, so it is returned for ``CLIENT`` and for ``SERVER``, and asking for ``ALL`` returns every loaded flag. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "The runtime to match, as a ``FeatureFlagEvaluationRuntime`` or its string value.", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nclient_keys = posthog.get_feature_flag_keys_by_evaluation_runtime(\n FeatureFlagEvaluationRuntime.CLIENT\n)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user, preserving valid serialized JSON.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Optional[str]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team'). Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and end the consumer threads. Do not use directly, call `shutdown()` instead. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Attempt final delivery and permanently shut down the client. Call this for final process cleanup or when disposing of a client that will not be reused. It closes capture lanes, stops background workers and the feature flag poller, and tears down integrations. Do not call it at the end of each request or serverless invocation when the client is shared; call ``flush()`` before returning instead. A shut-down client cannot be reused; create a new client if needed. Normally this method blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Event draining has no timeout. Queued spans get one final flush with up to 30 seconds waiting for an in-flight flush, then a fresh 30-second drain budget; the last HTTP request is not cut short. Any spans it cannot send are discarded with a warning, as are spans still open. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. When called directly from an SDK callback such as ``on_error``, shutdown is deferred to avoid blocking the worker that invoked the callback. If the callback must coordinate a blocking shutdown, have it signal an application-owned thread and return before that thread calls shutdown. Do not wait inside the callback for another thread or task that calls a lifecycle method.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span. A forked child starts with no active span; pass the parent span to continue a trace across a fork.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog = Posthog(\"\", traces={\"service_name\": \"checkout-api\"})\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is delivered on an isolated queue with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name, normally one of the `$ai_*` event names. **kwargs: Same optional arguments as `capture()`.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import capture_ai\n\nuuid = capture_ai(\n \"$ai_generation\",\n distinct_id=\"user_123\",\n properties={\"$ai_model\": \"gpt-5\"},\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip. Overriding reserved exception properties through ``properties`` is deprecated and will stop working in the next major version.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation and omit flags that cannot be evaluated locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is ``True``. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Attempt immediate delivery of queued events and ended spans, keeping the global client reusable. Call ``flush()`` before a short-lived request or serverless invocation returns when using the shared module-level client. Use ``shutdown()`` only for final process cleanup or a client that will not be reused. Flush does not stop the background workers or feature flag poller, and does not end open spans. Returning does not guarantee server receipt: pending work can remain after a timeout or span export failure, and failed events may be dropped by consumers. Calls made directly from SDK callbacks such as ``on_error`` are deferred rather than blocking the worker that invoked the callback.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Seconds to wait for event queues to drain, shared across event lanes. Defaults to 10 seconds. Pass ``None`` to wait without a time limit; this does not guarantee successful delivery. Queued spans flush concurrently, waiting up to this many seconds for an in-flight flush before starting a fresh drain budget. A lock wait timeout leaves the in-flight flush to finish. At least one span request is attempted after acquiring the lock, even with no budget left; retriable failures are retried after backoff while budget remains, with one last attempt at the deadline. The last span request is not cut short and is bounded by the client's ``timeout`` in seconds, so this is not a strict wall-clock limit for the whole call. With ``None``, a retriable span failure is left for a later flush rather than retried within this call.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "import posthog\nposthog.capture('event_name', distinct_id='user_id')\n# Before a serverless invocation returns; keep the global client open.\nposthog.flush(timeout_seconds=10)" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "Reads the `evaluation_runtime` each flag definition carries, so no extra request is made. Returns `None` when local evaluation has not loaded a definition for this key. A definition that carries no runtime reports `FeatureFlagEvaluationRuntime.ALL`, the default PostHog applies.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_evaluation_runtime\nruntime = get_feature_flag_evaluation_runtime(\"my-flag\")" - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate.", - "details": "A flag set to `FeatureFlagEvaluationRuntime.ALL` suits either runtime, so it is returned for `CLIENT` and for `SERVER`. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_keys_by_evaluation_runtime\nclient_keys = get_feature_flag_keys_by_evaluation_runtime(FeatureFlagEvaluationRuntime.CLIENT)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and stop the client's background workers. Use `shutdown()` directly in most cases. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Attempt final delivery and permanently shut down the global client. Call this for final process cleanup, not at the end of each request or serverless invocation that shares the module-level client. Use ``flush()`` before returning from those invocations instead. Shutdown closes capture lanes, stops background workers and the feature flag poller, and tears down integrations. The global client is not recreated automatically after shutdown. This normally blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Event draining has no timeout. Queued spans get a final flush with up to 30 seconds waiting for an in-flight flush, then a fresh 30-second drain budget; the last HTTP request is not cut short. Unsent queued spans and still-open spans are discarded with a warning. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. Calls made directly from SDK callbacks such as ``on_error`` are deferred to avoid deadlocking the worker. If blocking completion is required, signal an application-owned thread, return from the callback, and call ``shutdown()`` from that thread. Do not wait inside a callback for another thread or task calling a lifecycle method.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "import posthog\nposthog.traces = {\"service_name\": \"checkout-api\"}\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Tracing", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.75.0.json b/references/posthog-python-references-7.75.0.json deleted file mode 100644 index 23d13e277..000000000 --- a/references/posthog-python-references-7.75.0.json +++ /dev/null @@ -1,3548 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.75.0", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "enable_full_ai_capture", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_trace_context", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "traces", - "description": "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.", - "isOptional": true, - "type": "dict" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to. Falls back to the context distinct ID; the call is dropped with a warning if neither is available.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is queued on an isolated AI lane with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is True. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Attempt immediate delivery of queued events and ended spans, keeping the client reusable. For a client shared across requests or serverless invocations (including the module-level client), call ``flush()`` before a short-lived invocation returns. Use ``shutdown()`` instead only for final process cleanup or when disposing of a client that will not be reused. Flush does not stop the background workers or feature flag poller, and does not end open spans. Returning does not guarantee server receipt: pending work can remain after a timeout or span export failure, and failed events may be dropped by the consumers. Calls made directly from SDK callbacks such as ``on_error`` are deferred rather than blocking the worker that invoked the callback.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Seconds to wait for event queues to drain, shared across event lanes. Defaults to 10 seconds. Pass ``None`` to wait without a time limit; this does not guarantee successful delivery. Queued spans flush concurrently. The span exporter waits up to this many seconds for an in-flight flush, then uses a fresh drain budget once it acquires the lock. If the lock wait times out, the in-flight flush is left to finish. At least one span request is attempted after acquiring the lock, even with no budget left; retriable failures are retried after backoff while budget remains, with one last attempt at the deadline. Each span request is bounded by the client's ``timeout`` in seconds, and the last request is not cut short. This is therefore not a strict wall-clock limit for the whole call. With ``None``, a retriable span failure is left for a later flush rather than retried within this call.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name', distinct_id='user_id')\n# Before a serverless invocation returns; keep the shared client open.\nposthog.flush(timeout_seconds=10)" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nruntime = posthog.get_feature_flag_evaluation_runtime(\"my-flag\")\nif runtime is FeatureFlagEvaluationRuntime.SERVER:\n ..." - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate. A flag set to ``FeatureFlagEvaluationRuntime.ALL`` suits either runtime, so it is returned for ``CLIENT`` and for ``SERVER``, and asking for ``ALL`` returns every loaded flag. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "The runtime to match, as a ``FeatureFlagEvaluationRuntime`` or its string value.", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nclient_keys = posthog.get_feature_flag_keys_by_evaluation_runtime(\n FeatureFlagEvaluationRuntime.CLIENT\n)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user, preserving valid serialized JSON.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Optional[str]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team'). Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and end the consumer threads. Do not use directly, call `shutdown()` instead. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Attempt final delivery and permanently shut down the client. Call this for final process cleanup or when disposing of a client that will not be reused. It closes capture lanes, stops background workers and the feature flag poller, and tears down integrations. Do not call it at the end of each request or serverless invocation when the client is shared; call ``flush()`` before returning instead. A shut-down client cannot be reused; create a new client if needed. Normally this method blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Event draining has no timeout. Queued spans get one final flush with up to 30 seconds waiting for an in-flight flush, then a fresh 30-second drain budget; the last HTTP request is not cut short. Any spans it cannot send are discarded with a warning, as are spans still open. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. When called directly from an SDK callback such as ``on_error``, shutdown is deferred to avoid blocking the worker that invoked the callback. If the callback must coordinate a blocking shutdown, have it signal an application-owned thread and return before that thread calls shutdown. Do not wait inside the callback for another thread or task that calls a lifecycle method.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span. A forked child starts with no active span; pass the parent span to continue a trace across a fork.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog = Posthog(\"\", traces={\"service_name\": \"checkout-api\"})\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is delivered on an isolated queue with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name, normally one of the `$ai_*` event names. **kwargs: Same optional arguments as `capture()`.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import capture_ai\n\nuuid = capture_ai(\n \"$ai_generation\",\n distinct_id=\"user_123\",\n properties={\"$ai_model\": \"gpt-5\"},\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip. Overriding reserved exception properties through ``properties`` is deprecated and will stop working in the next major version.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation and omit flags that cannot be evaluated locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is ``True``. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Attempt immediate delivery of queued events and ended spans, keeping the global client reusable. Call ``flush()`` before a short-lived request or serverless invocation returns when using the shared module-level client. Use ``shutdown()`` only for final process cleanup or a client that will not be reused. Flush does not stop the background workers or feature flag poller, and does not end open spans. Returning does not guarantee server receipt: pending work can remain after a timeout or span export failure, and failed events may be dropped by consumers. Calls made directly from SDK callbacks such as ``on_error`` are deferred rather than blocking the worker that invoked the callback.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Seconds to wait for event queues to drain, shared across event lanes. Defaults to 10 seconds. Pass ``None`` to wait without a time limit; this does not guarantee successful delivery. Queued spans flush concurrently, waiting up to this many seconds for an in-flight flush before starting a fresh drain budget. A lock wait timeout leaves the in-flight flush to finish. At least one span request is attempted after acquiring the lock, even with no budget left; retriable failures are retried after backoff while budget remains, with one last attempt at the deadline. The last span request is not cut short and is bounded by the client's ``timeout`` in seconds, so this is not a strict wall-clock limit for the whole call. With ``None``, a retriable span failure is left for a later flush rather than retried within this call.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "import posthog\nposthog.capture('event_name', distinct_id='user_id')\n# Before a serverless invocation returns; keep the global client open.\nposthog.flush(timeout_seconds=10)" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "Reads the `evaluation_runtime` each flag definition carries, so no extra request is made. Returns `None` when local evaluation has not loaded a definition for this key. A definition that carries no runtime reports `FeatureFlagEvaluationRuntime.ALL`, the default PostHog applies.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_evaluation_runtime\nruntime = get_feature_flag_evaluation_runtime(\"my-flag\")" - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate.", - "details": "A flag set to `FeatureFlagEvaluationRuntime.ALL` suits either runtime, so it is returned for `CLIENT` and for `SERVER`. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_keys_by_evaluation_runtime\nclient_keys = get_feature_flag_keys_by_evaluation_runtime(FeatureFlagEvaluationRuntime.CLIENT)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and stop the client's background workers. Use `shutdown()` directly in most cases. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Attempt final delivery and permanently shut down the global client. Call this for final process cleanup, not at the end of each request or serverless invocation that shares the module-level client. Use ``flush()`` before returning from those invocations instead. Shutdown closes capture lanes, stops background workers and the feature flag poller, and tears down integrations. The global client is not recreated automatically after shutdown. This normally blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Event draining has no timeout. Queued spans get a final flush with up to 30 seconds waiting for an in-flight flush, then a fresh 30-second drain budget; the last HTTP request is not cut short. Unsent queued spans and still-open spans are discarded with a warning. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. Calls made directly from SDK callbacks such as ``on_error`` are deferred to avoid deadlocking the worker. If blocking completion is required, signal an application-owned thread, return from the callback, and call ``shutdown()`` from that thread. Do not wait inside a callback for another thread or task calling a lifecycle method.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "import posthog\nposthog.traces = {\"service_name\": \"checkout-api\"}\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Tracing", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.75.1.json b/references/posthog-python-references-7.75.1.json deleted file mode 100644 index 738621f18..000000000 --- a/references/posthog-python-references-7.75.1.json +++ /dev/null @@ -1,3548 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.75.1", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "enable_full_ai_capture", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_trace_context", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "traces", - "description": "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.", - "isOptional": true, - "type": "dict" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to. Falls back to the context distinct ID; the call is dropped with a warning if neither is available.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is queued on an isolated AI lane with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is True. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Attempt immediate delivery of queued events and ended spans, keeping the client reusable. For a client shared across requests or serverless invocations (including the module-level client), call ``flush()`` before a short-lived invocation returns. Use ``shutdown()`` instead only for final process cleanup or when disposing of a client that will not be reused. Flush does not stop the background workers or feature flag poller, and does not end open spans. Returning does not guarantee server receipt: pending work can remain after a timeout or span export failure, and failed events may be dropped by the consumers. Calls made directly from SDK callbacks such as ``on_error`` are deferred rather than blocking the worker that invoked the callback.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Seconds to wait for event queues to drain, shared across event lanes. Defaults to 10 seconds. Pass ``None`` to wait without a time limit; this does not guarantee successful delivery. Queued spans flush concurrently. The span exporter waits up to this many seconds for an in-flight flush, then uses a fresh drain budget once it acquires the lock. If the lock wait times out, the in-flight flush is left to finish. At least one span request is attempted after acquiring the lock, even with no budget left; retriable failures are retried after backoff while budget remains, with one last attempt at the deadline. Each span request is bounded by the client's ``timeout`` in seconds, and the last request is not cut short. This is therefore not a strict wall-clock limit for the whole call. With ``None``, a retriable span failure is left for a later flush rather than retried within this call.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name', distinct_id='user_id')\n# Before a serverless invocation returns; keep the shared client open.\nposthog.flush(timeout_seconds=10)" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nruntime = posthog.get_feature_flag_evaluation_runtime(\"my-flag\")\nif runtime is FeatureFlagEvaluationRuntime.SERVER:\n ..." - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate. A flag set to ``FeatureFlagEvaluationRuntime.ALL`` suits either runtime, so it is returned for ``CLIENT`` and for ``SERVER``, and asking for ``ALL`` returns every loaded flag. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "The runtime to match, as a ``FeatureFlagEvaluationRuntime`` or its string value.", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nclient_keys = posthog.get_feature_flag_keys_by_evaluation_runtime(\n FeatureFlagEvaluationRuntime.CLIENT\n)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user, preserving valid serialized JSON.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Optional[str]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team'). Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and end the consumer threads. Do not use directly, call `shutdown()` instead. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Attempt final delivery and permanently shut down the client. Call this for final process cleanup or when disposing of a client that will not be reused. It closes capture lanes, stops background workers and the feature flag poller, and tears down integrations. Do not call it at the end of each request or serverless invocation when the client is shared; call ``flush()`` before returning instead. A shut-down client cannot be reused; create a new client if needed. Normally this method blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Event draining has no timeout. Queued spans get one final flush with up to 30 seconds waiting for an in-flight flush, then a fresh 30-second drain budget; the last HTTP request is not cut short. Any spans it cannot send are discarded with a warning, as are spans still open. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. When called directly from an SDK callback such as ``on_error``, shutdown is deferred to avoid blocking the worker that invoked the callback. If the callback must coordinate a blocking shutdown, have it signal an application-owned thread and return before that thread calls shutdown. Do not wait inside the callback for another thread or task that calls a lifecycle method.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span. A forked child starts with no active span; pass the parent span to continue a trace across a fork.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog = Posthog(\"\", traces={\"service_name\": \"checkout-api\"})\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is delivered on an isolated queue with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name, normally one of the `$ai_*` event names. **kwargs: Same optional arguments as `capture()`.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import capture_ai\n\nuuid = capture_ai(\n \"$ai_generation\",\n distinct_id=\"user_123\",\n properties={\"$ai_model\": \"gpt-5\"},\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip. Overriding reserved exception properties through ``properties`` is deprecated and will stop working in the next major version.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation and omit flags that cannot be evaluated locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is ``True``. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Attempt immediate delivery of queued events and ended spans, keeping the global client reusable. Call ``flush()`` before a short-lived request or serverless invocation returns when using the shared module-level client. Use ``shutdown()`` only for final process cleanup or a client that will not be reused. Flush does not stop the background workers or feature flag poller, and does not end open spans. Returning does not guarantee server receipt: pending work can remain after a timeout or span export failure, and failed events may be dropped by consumers. Calls made directly from SDK callbacks such as ``on_error`` are deferred rather than blocking the worker that invoked the callback.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Seconds to wait for event queues to drain, shared across event lanes. Defaults to 10 seconds. Pass ``None`` to wait without a time limit; this does not guarantee successful delivery. Queued spans flush concurrently, waiting up to this many seconds for an in-flight flush before starting a fresh drain budget. A lock wait timeout leaves the in-flight flush to finish. At least one span request is attempted after acquiring the lock, even with no budget left; retriable failures are retried after backoff while budget remains, with one last attempt at the deadline. The last span request is not cut short and is bounded by the client's ``timeout`` in seconds, so this is not a strict wall-clock limit for the whole call. With ``None``, a retriable span failure is left for a later flush rather than retried within this call.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "import posthog\nposthog.capture('event_name', distinct_id='user_id')\n# Before a serverless invocation returns; keep the global client open.\nposthog.flush(timeout_seconds=10)" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "Reads the `evaluation_runtime` each flag definition carries, so no extra request is made. Returns `None` when local evaluation has not loaded a definition for this key. A definition that carries no runtime reports `FeatureFlagEvaluationRuntime.ALL`, the default PostHog applies.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_evaluation_runtime\nruntime = get_feature_flag_evaluation_runtime(\"my-flag\")" - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate.", - "details": "A flag set to `FeatureFlagEvaluationRuntime.ALL` suits either runtime, so it is returned for `CLIENT` and for `SERVER`. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_keys_by_evaluation_runtime\nclient_keys = get_feature_flag_keys_by_evaluation_runtime(FeatureFlagEvaluationRuntime.CLIENT)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and stop the client's background workers. Use `shutdown()` directly in most cases. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Attempt final delivery and permanently shut down the global client. Call this for final process cleanup, not at the end of each request or serverless invocation that shares the module-level client. Use ``flush()`` before returning from those invocations instead. Shutdown closes capture lanes, stops background workers and the feature flag poller, and tears down integrations. The global client is not recreated automatically after shutdown. This normally blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Event draining has no timeout. Queued spans get a final flush with up to 30 seconds waiting for an in-flight flush, then a fresh 30-second drain budget; the last HTTP request is not cut short. Unsent queued spans and still-open spans are discarded with a warning. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. Calls made directly from SDK callbacks such as ``on_error`` are deferred to avoid deadlocking the worker. If blocking completion is required, signal an application-owned thread, return from the callback, and call ``shutdown()`` from that thread. Do not wait inside a callback for another thread or task calling a lifecycle method.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "import posthog\nposthog.traces = {\"service_name\": \"checkout-api\"}\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Tracing", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.75.10.json b/references/posthog-python-references-7.75.10.json deleted file mode 100644 index 226ca01c2..000000000 --- a/references/posthog-python-references-7.75.10.json +++ /dev/null @@ -1,3548 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.75.10", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "float" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "float" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "enable_full_ai_capture", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_trace_context", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "traces", - "description": "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.", - "isOptional": true, - "type": "dict" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to. Falls back to the context distinct ID; the call is dropped with a warning if neither is available.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is queued on an isolated AI lane with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is True. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Attempt immediate delivery of queued events and ended spans, keeping the client reusable. For a client shared across requests or serverless invocations (including the module-level client), call ``flush()`` before a short-lived invocation returns. Use ``shutdown()`` instead only for final process cleanup or when disposing of a client that will not be reused. Flush does not stop the background workers or feature flag poller, and does not end open spans. Returning does not guarantee server receipt: pending work can remain after a timeout or span export failure, and failed events may be dropped by the consumers. Calls made directly from SDK callbacks such as ``on_error`` are deferred rather than blocking the worker that invoked the callback.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Seconds to wait for event queues to drain, shared across event lanes. Defaults to 10 seconds. Pass ``None`` to wait without a time limit; this does not guarantee successful delivery. Queued spans flush concurrently. The span exporter waits up to this many seconds for an in-flight flush, then uses a fresh drain budget once it acquires the lock. If the lock wait times out, the in-flight flush is left to finish. At least one span request is attempted after acquiring the lock, even with no budget left; retriable failures are retried after backoff while budget remains, with one last attempt at the deadline. Each span request is bounded by the client's ``timeout`` in seconds, and the last request is not cut short. This is therefore not a strict wall-clock limit for the whole call. With ``None``, a retriable span failure is left for a later flush rather than retried within this call.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name', distinct_id='user_id')\n# Before a serverless invocation returns; keep the shared client open.\nposthog.flush(timeout_seconds=10)" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nruntime = posthog.get_feature_flag_evaluation_runtime(\"my-flag\")\nif runtime is FeatureFlagEvaluationRuntime.SERVER:\n ..." - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate. A flag set to ``FeatureFlagEvaluationRuntime.ALL`` suits either runtime, so it is returned for ``CLIENT`` and for ``SERVER``, and asking for ``ALL`` returns every loaded flag. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "The runtime to match, as a ``FeatureFlagEvaluationRuntime`` or its string value.", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nclient_keys = posthog.get_feature_flag_keys_by_evaluation_runtime(\n FeatureFlagEvaluationRuntime.CLIENT\n)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user, preserving valid serialized JSON.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Optional[str]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team'). Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and end the consumer threads. Do not use directly, call `shutdown()` instead. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Attempt final delivery and permanently shut down the client. Call this for final process cleanup or when disposing of a client that will not be reused. It closes capture lanes, stops background workers and the feature flag poller, and tears down integrations. Do not call it at the end of each request or serverless invocation when the client is shared; call ``flush()`` before returning instead. A shut-down client cannot be reused; create a new client if needed. Normally this method blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Event draining has no timeout. Queued spans get one final flush with up to 30 seconds waiting for an in-flight flush, then a fresh 30-second drain budget; the last HTTP request is not cut short. Any spans it cannot send are discarded with a warning, as are spans still open. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. When called directly from an SDK callback such as ``on_error``, shutdown is deferred to avoid blocking the worker that invoked the callback. If the callback must coordinate a blocking shutdown, have it signal an application-owned thread and return before that thread calls shutdown. Do not wait inside the callback for another thread or task that calls a lifecycle method.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span. A forked child starts with no active span; pass the parent span to continue a trace across a fork.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog = Posthog(\"\", traces={\"service_name\": \"checkout-api\"})\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is delivered on an isolated queue with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name, normally one of the `$ai_*` event names. **kwargs: Same optional arguments as `capture()`.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import capture_ai\n\nuuid = capture_ai(\n \"$ai_generation\",\n distinct_id=\"user_123\",\n properties={\"$ai_model\": \"gpt-5\"},\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip. Overriding reserved exception properties through ``properties`` is deprecated and will stop working in the next major version.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation and omit flags that cannot be evaluated locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is ``True``. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Attempt immediate delivery of queued events and ended spans, keeping the global client reusable. Call ``flush()`` before a short-lived request or serverless invocation returns when using the shared module-level client. Use ``shutdown()`` only for final process cleanup or a client that will not be reused. Flush does not stop the background workers or feature flag poller, and does not end open spans. Returning does not guarantee server receipt: pending work can remain after a timeout or span export failure, and failed events may be dropped by consumers. Calls made directly from SDK callbacks such as ``on_error`` are deferred rather than blocking the worker that invoked the callback.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Seconds to wait for event queues to drain, shared across event lanes. Defaults to 10 seconds. Pass ``None`` to wait without a time limit; this does not guarantee successful delivery. Queued spans flush concurrently, waiting up to this many seconds for an in-flight flush before starting a fresh drain budget. A lock wait timeout leaves the in-flight flush to finish. At least one span request is attempted after acquiring the lock, even with no budget left; retriable failures are retried after backoff while budget remains, with one last attempt at the deadline. The last span request is not cut short and is bounded by the client's ``timeout`` in seconds, so this is not a strict wall-clock limit for the whole call. With ``None``, a retriable span failure is left for a later flush rather than retried within this call.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "import posthog\nposthog.capture('event_name', distinct_id='user_id')\n# Before a serverless invocation returns; keep the global client open.\nposthog.flush(timeout_seconds=10)" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "Reads the `evaluation_runtime` each flag definition carries, so no extra request is made. Returns `None` when local evaluation has not loaded a definition for this key. A definition that carries no runtime reports `FeatureFlagEvaluationRuntime.ALL`, the default PostHog applies.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_evaluation_runtime\nruntime = get_feature_flag_evaluation_runtime(\"my-flag\")" - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate.", - "details": "A flag set to `FeatureFlagEvaluationRuntime.ALL` suits either runtime, so it is returned for `CLIENT` and for `SERVER`. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_keys_by_evaluation_runtime\nclient_keys = get_feature_flag_keys_by_evaluation_runtime(FeatureFlagEvaluationRuntime.CLIENT)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and stop the client's background workers. Use `shutdown()` directly in most cases. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Attempt final delivery and permanently shut down the global client. Call this for final process cleanup, not at the end of each request or serverless invocation that shares the module-level client. Use ``flush()`` before returning from those invocations instead. Shutdown closes capture lanes, stops background workers and the feature flag poller, and tears down integrations. The global client is not recreated automatically after shutdown. This normally blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Event draining has no timeout. Queued spans get a final flush with up to 30 seconds waiting for an in-flight flush, then a fresh 30-second drain budget; the last HTTP request is not cut short. Unsent queued spans and still-open spans are discarded with a warning. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. Calls made directly from SDK callbacks such as ``on_error`` are deferred to avoid deadlocking the worker. If blocking completion is required, signal an application-owned thread, return from the callback, and call ``shutdown()`` from that thread. Do not wait inside a callback for another thread or task calling a lifecycle method.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "import posthog\nposthog.traces = {\"service_name\": \"checkout-api\"}\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Tracing", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.75.2.json b/references/posthog-python-references-7.75.2.json deleted file mode 100644 index 6b0cdcdf1..000000000 --- a/references/posthog-python-references-7.75.2.json +++ /dev/null @@ -1,3548 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.75.2", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "enable_full_ai_capture", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_trace_context", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "traces", - "description": "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.", - "isOptional": true, - "type": "dict" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to. Falls back to the context distinct ID; the call is dropped with a warning if neither is available.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is queued on an isolated AI lane with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is True. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Attempt immediate delivery of queued events and ended spans, keeping the client reusable. For a client shared across requests or serverless invocations (including the module-level client), call ``flush()`` before a short-lived invocation returns. Use ``shutdown()`` instead only for final process cleanup or when disposing of a client that will not be reused. Flush does not stop the background workers or feature flag poller, and does not end open spans. Returning does not guarantee server receipt: pending work can remain after a timeout or span export failure, and failed events may be dropped by the consumers. Calls made directly from SDK callbacks such as ``on_error`` are deferred rather than blocking the worker that invoked the callback.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Seconds to wait for event queues to drain, shared across event lanes. Defaults to 10 seconds. Pass ``None`` to wait without a time limit; this does not guarantee successful delivery. Queued spans flush concurrently. The span exporter waits up to this many seconds for an in-flight flush, then uses a fresh drain budget once it acquires the lock. If the lock wait times out, the in-flight flush is left to finish. At least one span request is attempted after acquiring the lock, even with no budget left; retriable failures are retried after backoff while budget remains, with one last attempt at the deadline. Each span request is bounded by the client's ``timeout`` in seconds, and the last request is not cut short. This is therefore not a strict wall-clock limit for the whole call. With ``None``, a retriable span failure is left for a later flush rather than retried within this call.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name', distinct_id='user_id')\n# Before a serverless invocation returns; keep the shared client open.\nposthog.flush(timeout_seconds=10)" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nruntime = posthog.get_feature_flag_evaluation_runtime(\"my-flag\")\nif runtime is FeatureFlagEvaluationRuntime.SERVER:\n ..." - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate. A flag set to ``FeatureFlagEvaluationRuntime.ALL`` suits either runtime, so it is returned for ``CLIENT`` and for ``SERVER``, and asking for ``ALL`` returns every loaded flag. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "The runtime to match, as a ``FeatureFlagEvaluationRuntime`` or its string value.", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nclient_keys = posthog.get_feature_flag_keys_by_evaluation_runtime(\n FeatureFlagEvaluationRuntime.CLIENT\n)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user, preserving valid serialized JSON.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Optional[str]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team'). Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and end the consumer threads. Do not use directly, call `shutdown()` instead. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Attempt final delivery and permanently shut down the client. Call this for final process cleanup or when disposing of a client that will not be reused. It closes capture lanes, stops background workers and the feature flag poller, and tears down integrations. Do not call it at the end of each request or serverless invocation when the client is shared; call ``flush()`` before returning instead. A shut-down client cannot be reused; create a new client if needed. Normally this method blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Event draining has no timeout. Queued spans get one final flush with up to 30 seconds waiting for an in-flight flush, then a fresh 30-second drain budget; the last HTTP request is not cut short. Any spans it cannot send are discarded with a warning, as are spans still open. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. When called directly from an SDK callback such as ``on_error``, shutdown is deferred to avoid blocking the worker that invoked the callback. If the callback must coordinate a blocking shutdown, have it signal an application-owned thread and return before that thread calls shutdown. Do not wait inside the callback for another thread or task that calls a lifecycle method.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span. A forked child starts with no active span; pass the parent span to continue a trace across a fork.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog = Posthog(\"\", traces={\"service_name\": \"checkout-api\"})\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is delivered on an isolated queue with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name, normally one of the `$ai_*` event names. **kwargs: Same optional arguments as `capture()`.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import capture_ai\n\nuuid = capture_ai(\n \"$ai_generation\",\n distinct_id=\"user_123\",\n properties={\"$ai_model\": \"gpt-5\"},\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip. Overriding reserved exception properties through ``properties`` is deprecated and will stop working in the next major version.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation and omit flags that cannot be evaluated locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is ``True``. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Attempt immediate delivery of queued events and ended spans, keeping the global client reusable. Call ``flush()`` before a short-lived request or serverless invocation returns when using the shared module-level client. Use ``shutdown()`` only for final process cleanup or a client that will not be reused. Flush does not stop the background workers or feature flag poller, and does not end open spans. Returning does not guarantee server receipt: pending work can remain after a timeout or span export failure, and failed events may be dropped by consumers. Calls made directly from SDK callbacks such as ``on_error`` are deferred rather than blocking the worker that invoked the callback.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Seconds to wait for event queues to drain, shared across event lanes. Defaults to 10 seconds. Pass ``None`` to wait without a time limit; this does not guarantee successful delivery. Queued spans flush concurrently, waiting up to this many seconds for an in-flight flush before starting a fresh drain budget. A lock wait timeout leaves the in-flight flush to finish. At least one span request is attempted after acquiring the lock, even with no budget left; retriable failures are retried after backoff while budget remains, with one last attempt at the deadline. The last span request is not cut short and is bounded by the client's ``timeout`` in seconds, so this is not a strict wall-clock limit for the whole call. With ``None``, a retriable span failure is left for a later flush rather than retried within this call.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "import posthog\nposthog.capture('event_name', distinct_id='user_id')\n# Before a serverless invocation returns; keep the global client open.\nposthog.flush(timeout_seconds=10)" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "Reads the `evaluation_runtime` each flag definition carries, so no extra request is made. Returns `None` when local evaluation has not loaded a definition for this key. A definition that carries no runtime reports `FeatureFlagEvaluationRuntime.ALL`, the default PostHog applies.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_evaluation_runtime\nruntime = get_feature_flag_evaluation_runtime(\"my-flag\")" - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate.", - "details": "A flag set to `FeatureFlagEvaluationRuntime.ALL` suits either runtime, so it is returned for `CLIENT` and for `SERVER`. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_keys_by_evaluation_runtime\nclient_keys = get_feature_flag_keys_by_evaluation_runtime(FeatureFlagEvaluationRuntime.CLIENT)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and stop the client's background workers. Use `shutdown()` directly in most cases. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Attempt final delivery and permanently shut down the global client. Call this for final process cleanup, not at the end of each request or serverless invocation that shares the module-level client. Use ``flush()`` before returning from those invocations instead. Shutdown closes capture lanes, stops background workers and the feature flag poller, and tears down integrations. The global client is not recreated automatically after shutdown. This normally blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Event draining has no timeout. Queued spans get a final flush with up to 30 seconds waiting for an in-flight flush, then a fresh 30-second drain budget; the last HTTP request is not cut short. Unsent queued spans and still-open spans are discarded with a warning. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. Calls made directly from SDK callbacks such as ``on_error`` are deferred to avoid deadlocking the worker. If blocking completion is required, signal an application-owned thread, return from the callback, and call ``shutdown()`` from that thread. Do not wait inside a callback for another thread or task calling a lifecycle method.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "import posthog\nposthog.traces = {\"service_name\": \"checkout-api\"}\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Tracing", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.75.3.json b/references/posthog-python-references-7.75.3.json deleted file mode 100644 index 03f87f17f..000000000 --- a/references/posthog-python-references-7.75.3.json +++ /dev/null @@ -1,3548 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.75.3", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "enable_full_ai_capture", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_trace_context", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "traces", - "description": "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.", - "isOptional": true, - "type": "dict" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to. Falls back to the context distinct ID; the call is dropped with a warning if neither is available.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is queued on an isolated AI lane with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is True. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Attempt immediate delivery of queued events and ended spans, keeping the client reusable. For a client shared across requests or serverless invocations (including the module-level client), call ``flush()`` before a short-lived invocation returns. Use ``shutdown()`` instead only for final process cleanup or when disposing of a client that will not be reused. Flush does not stop the background workers or feature flag poller, and does not end open spans. Returning does not guarantee server receipt: pending work can remain after a timeout or span export failure, and failed events may be dropped by the consumers. Calls made directly from SDK callbacks such as ``on_error`` are deferred rather than blocking the worker that invoked the callback.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Seconds to wait for event queues to drain, shared across event lanes. Defaults to 10 seconds. Pass ``None`` to wait without a time limit; this does not guarantee successful delivery. Queued spans flush concurrently. The span exporter waits up to this many seconds for an in-flight flush, then uses a fresh drain budget once it acquires the lock. If the lock wait times out, the in-flight flush is left to finish. At least one span request is attempted after acquiring the lock, even with no budget left; retriable failures are retried after backoff while budget remains, with one last attempt at the deadline. Each span request is bounded by the client's ``timeout`` in seconds, and the last request is not cut short. This is therefore not a strict wall-clock limit for the whole call. With ``None``, a retriable span failure is left for a later flush rather than retried within this call.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name', distinct_id='user_id')\n# Before a serverless invocation returns; keep the shared client open.\nposthog.flush(timeout_seconds=10)" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nruntime = posthog.get_feature_flag_evaluation_runtime(\"my-flag\")\nif runtime is FeatureFlagEvaluationRuntime.SERVER:\n ..." - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate. A flag set to ``FeatureFlagEvaluationRuntime.ALL`` suits either runtime, so it is returned for ``CLIENT`` and for ``SERVER``, and asking for ``ALL`` returns every loaded flag. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "The runtime to match, as a ``FeatureFlagEvaluationRuntime`` or its string value.", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nclient_keys = posthog.get_feature_flag_keys_by_evaluation_runtime(\n FeatureFlagEvaluationRuntime.CLIENT\n)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user, preserving valid serialized JSON.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Optional[str]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team'). Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and end the consumer threads. Do not use directly, call `shutdown()` instead. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Attempt final delivery and permanently shut down the client. Call this for final process cleanup or when disposing of a client that will not be reused. It closes capture lanes, stops background workers and the feature flag poller, and tears down integrations. Do not call it at the end of each request or serverless invocation when the client is shared; call ``flush()`` before returning instead. A shut-down client cannot be reused; create a new client if needed. Normally this method blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Event draining has no timeout. Queued spans get one final flush with up to 30 seconds waiting for an in-flight flush, then a fresh 30-second drain budget; the last HTTP request is not cut short. Any spans it cannot send are discarded with a warning, as are spans still open. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. When called directly from an SDK callback such as ``on_error``, shutdown is deferred to avoid blocking the worker that invoked the callback. If the callback must coordinate a blocking shutdown, have it signal an application-owned thread and return before that thread calls shutdown. Do not wait inside the callback for another thread or task that calls a lifecycle method.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span. A forked child starts with no active span; pass the parent span to continue a trace across a fork.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog = Posthog(\"\", traces={\"service_name\": \"checkout-api\"})\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is delivered on an isolated queue with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name, normally one of the `$ai_*` event names. **kwargs: Same optional arguments as `capture()`.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import capture_ai\n\nuuid = capture_ai(\n \"$ai_generation\",\n distinct_id=\"user_123\",\n properties={\"$ai_model\": \"gpt-5\"},\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip. Overriding reserved exception properties through ``properties`` is deprecated and will stop working in the next major version.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation and omit flags that cannot be evaluated locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is ``True``. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Attempt immediate delivery of queued events and ended spans, keeping the global client reusable. Call ``flush()`` before a short-lived request or serverless invocation returns when using the shared module-level client. Use ``shutdown()`` only for final process cleanup or a client that will not be reused. Flush does not stop the background workers or feature flag poller, and does not end open spans. Returning does not guarantee server receipt: pending work can remain after a timeout or span export failure, and failed events may be dropped by consumers. Calls made directly from SDK callbacks such as ``on_error`` are deferred rather than blocking the worker that invoked the callback.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Seconds to wait for event queues to drain, shared across event lanes. Defaults to 10 seconds. Pass ``None`` to wait without a time limit; this does not guarantee successful delivery. Queued spans flush concurrently, waiting up to this many seconds for an in-flight flush before starting a fresh drain budget. A lock wait timeout leaves the in-flight flush to finish. At least one span request is attempted after acquiring the lock, even with no budget left; retriable failures are retried after backoff while budget remains, with one last attempt at the deadline. The last span request is not cut short and is bounded by the client's ``timeout`` in seconds, so this is not a strict wall-clock limit for the whole call. With ``None``, a retriable span failure is left for a later flush rather than retried within this call.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "import posthog\nposthog.capture('event_name', distinct_id='user_id')\n# Before a serverless invocation returns; keep the global client open.\nposthog.flush(timeout_seconds=10)" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "Reads the `evaluation_runtime` each flag definition carries, so no extra request is made. Returns `None` when local evaluation has not loaded a definition for this key. A definition that carries no runtime reports `FeatureFlagEvaluationRuntime.ALL`, the default PostHog applies.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_evaluation_runtime\nruntime = get_feature_flag_evaluation_runtime(\"my-flag\")" - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate.", - "details": "A flag set to `FeatureFlagEvaluationRuntime.ALL` suits either runtime, so it is returned for `CLIENT` and for `SERVER`. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_keys_by_evaluation_runtime\nclient_keys = get_feature_flag_keys_by_evaluation_runtime(FeatureFlagEvaluationRuntime.CLIENT)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and stop the client's background workers. Use `shutdown()` directly in most cases. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Attempt final delivery and permanently shut down the global client. Call this for final process cleanup, not at the end of each request or serverless invocation that shares the module-level client. Use ``flush()`` before returning from those invocations instead. Shutdown closes capture lanes, stops background workers and the feature flag poller, and tears down integrations. The global client is not recreated automatically after shutdown. This normally blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Event draining has no timeout. Queued spans get a final flush with up to 30 seconds waiting for an in-flight flush, then a fresh 30-second drain budget; the last HTTP request is not cut short. Unsent queued spans and still-open spans are discarded with a warning. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. Calls made directly from SDK callbacks such as ``on_error`` are deferred to avoid deadlocking the worker. If blocking completion is required, signal an application-owned thread, return from the callback, and call ``shutdown()`` from that thread. Do not wait inside a callback for another thread or task calling a lifecycle method.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "import posthog\nposthog.traces = {\"service_name\": \"checkout-api\"}\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Tracing", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.75.4.json b/references/posthog-python-references-7.75.4.json deleted file mode 100644 index 2cd75278e..000000000 --- a/references/posthog-python-references-7.75.4.json +++ /dev/null @@ -1,3548 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.75.4", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "int" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "int" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "enable_full_ai_capture", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_trace_context", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "traces", - "description": "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.", - "isOptional": true, - "type": "dict" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to. Falls back to the context distinct ID; the call is dropped with a warning if neither is available.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is queued on an isolated AI lane with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is True. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Attempt immediate delivery of queued events and ended spans, keeping the client reusable. For a client shared across requests or serverless invocations (including the module-level client), call ``flush()`` before a short-lived invocation returns. Use ``shutdown()`` instead only for final process cleanup or when disposing of a client that will not be reused. Flush does not stop the background workers or feature flag poller, and does not end open spans. Returning does not guarantee server receipt: pending work can remain after a timeout or span export failure, and failed events may be dropped by the consumers. Calls made directly from SDK callbacks such as ``on_error`` are deferred rather than blocking the worker that invoked the callback.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Seconds to wait for event queues to drain, shared across event lanes. Defaults to 10 seconds. Pass ``None`` to wait without a time limit; this does not guarantee successful delivery. Queued spans flush concurrently. The span exporter waits up to this many seconds for an in-flight flush, then uses a fresh drain budget once it acquires the lock. If the lock wait times out, the in-flight flush is left to finish. At least one span request is attempted after acquiring the lock, even with no budget left; retriable failures are retried after backoff while budget remains, with one last attempt at the deadline. Each span request is bounded by the client's ``timeout`` in seconds, and the last request is not cut short. This is therefore not a strict wall-clock limit for the whole call. With ``None``, a retriable span failure is left for a later flush rather than retried within this call.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name', distinct_id='user_id')\n# Before a serverless invocation returns; keep the shared client open.\nposthog.flush(timeout_seconds=10)" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nruntime = posthog.get_feature_flag_evaluation_runtime(\"my-flag\")\nif runtime is FeatureFlagEvaluationRuntime.SERVER:\n ..." - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate. A flag set to ``FeatureFlagEvaluationRuntime.ALL`` suits either runtime, so it is returned for ``CLIENT`` and for ``SERVER``, and asking for ``ALL`` returns every loaded flag. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "The runtime to match, as a ``FeatureFlagEvaluationRuntime`` or its string value.", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nclient_keys = posthog.get_feature_flag_keys_by_evaluation_runtime(\n FeatureFlagEvaluationRuntime.CLIENT\n)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user, preserving valid serialized JSON.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Optional[str]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team'). Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and end the consumer threads. Do not use directly, call `shutdown()` instead. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Attempt final delivery and permanently shut down the client. Call this for final process cleanup or when disposing of a client that will not be reused. It closes capture lanes, stops background workers and the feature flag poller, and tears down integrations. Do not call it at the end of each request or serverless invocation when the client is shared; call ``flush()`` before returning instead. A shut-down client cannot be reused; create a new client if needed. Normally this method blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Event draining has no timeout. Queued spans get one final flush with up to 30 seconds waiting for an in-flight flush, then a fresh 30-second drain budget; the last HTTP request is not cut short. Any spans it cannot send are discarded with a warning, as are spans still open. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. When called directly from an SDK callback such as ``on_error``, shutdown is deferred to avoid blocking the worker that invoked the callback. If the callback must coordinate a blocking shutdown, have it signal an application-owned thread and return before that thread calls shutdown. Do not wait inside the callback for another thread or task that calls a lifecycle method.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span. A forked child starts with no active span; pass the parent span to continue a trace across a fork.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog = Posthog(\"\", traces={\"service_name\": \"checkout-api\"})\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is delivered on an isolated queue with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name, normally one of the `$ai_*` event names. **kwargs: Same optional arguments as `capture()`.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import capture_ai\n\nuuid = capture_ai(\n \"$ai_generation\",\n distinct_id=\"user_123\",\n properties={\"$ai_model\": \"gpt-5\"},\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip. Overriding reserved exception properties through ``properties`` is deprecated and will stop working in the next major version.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation and omit flags that cannot be evaluated locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is ``True``. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Attempt immediate delivery of queued events and ended spans, keeping the global client reusable. Call ``flush()`` before a short-lived request or serverless invocation returns when using the shared module-level client. Use ``shutdown()`` only for final process cleanup or a client that will not be reused. Flush does not stop the background workers or feature flag poller, and does not end open spans. Returning does not guarantee server receipt: pending work can remain after a timeout or span export failure, and failed events may be dropped by consumers. Calls made directly from SDK callbacks such as ``on_error`` are deferred rather than blocking the worker that invoked the callback.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Seconds to wait for event queues to drain, shared across event lanes. Defaults to 10 seconds. Pass ``None`` to wait without a time limit; this does not guarantee successful delivery. Queued spans flush concurrently, waiting up to this many seconds for an in-flight flush before starting a fresh drain budget. A lock wait timeout leaves the in-flight flush to finish. At least one span request is attempted after acquiring the lock, even with no budget left; retriable failures are retried after backoff while budget remains, with one last attempt at the deadline. The last span request is not cut short and is bounded by the client's ``timeout`` in seconds, so this is not a strict wall-clock limit for the whole call. With ``None``, a retriable span failure is left for a later flush rather than retried within this call.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "import posthog\nposthog.capture('event_name', distinct_id='user_id')\n# Before a serverless invocation returns; keep the global client open.\nposthog.flush(timeout_seconds=10)" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "Reads the `evaluation_runtime` each flag definition carries, so no extra request is made. Returns `None` when local evaluation has not loaded a definition for this key. A definition that carries no runtime reports `FeatureFlagEvaluationRuntime.ALL`, the default PostHog applies.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_evaluation_runtime\nruntime = get_feature_flag_evaluation_runtime(\"my-flag\")" - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate.", - "details": "A flag set to `FeatureFlagEvaluationRuntime.ALL` suits either runtime, so it is returned for `CLIENT` and for `SERVER`. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_keys_by_evaluation_runtime\nclient_keys = get_feature_flag_keys_by_evaluation_runtime(FeatureFlagEvaluationRuntime.CLIENT)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and stop the client's background workers. Use `shutdown()` directly in most cases. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Attempt final delivery and permanently shut down the global client. Call this for final process cleanup, not at the end of each request or serverless invocation that shares the module-level client. Use ``flush()`` before returning from those invocations instead. Shutdown closes capture lanes, stops background workers and the feature flag poller, and tears down integrations. The global client is not recreated automatically after shutdown. This normally blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Event draining has no timeout. Queued spans get a final flush with up to 30 seconds waiting for an in-flight flush, then a fresh 30-second drain budget; the last HTTP request is not cut short. Unsent queued spans and still-open spans are discarded with a warning. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. Calls made directly from SDK callbacks such as ``on_error`` are deferred to avoid deadlocking the worker. If blocking completion is required, signal an application-owned thread, return from the callback, and call ``shutdown()`` from that thread. Do not wait inside a callback for another thread or task calling a lifecycle method.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "import posthog\nposthog.traces = {\"service_name\": \"checkout-api\"}\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Tracing", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.75.5.json b/references/posthog-python-references-7.75.5.json deleted file mode 100644 index 342f66487..000000000 --- a/references/posthog-python-references-7.75.5.json +++ /dev/null @@ -1,3548 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.75.5", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "float" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "float" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "enable_full_ai_capture", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_trace_context", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "traces", - "description": "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.", - "isOptional": true, - "type": "dict" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to. Falls back to the context distinct ID; the call is dropped with a warning if neither is available.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is queued on an isolated AI lane with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is True. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Attempt immediate delivery of queued events and ended spans, keeping the client reusable. For a client shared across requests or serverless invocations (including the module-level client), call ``flush()`` before a short-lived invocation returns. Use ``shutdown()`` instead only for final process cleanup or when disposing of a client that will not be reused. Flush does not stop the background workers or feature flag poller, and does not end open spans. Returning does not guarantee server receipt: pending work can remain after a timeout or span export failure, and failed events may be dropped by the consumers. Calls made directly from SDK callbacks such as ``on_error`` are deferred rather than blocking the worker that invoked the callback.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Seconds to wait for event queues to drain, shared across event lanes. Defaults to 10 seconds. Pass ``None`` to wait without a time limit; this does not guarantee successful delivery. Queued spans flush concurrently. The span exporter waits up to this many seconds for an in-flight flush, then uses a fresh drain budget once it acquires the lock. If the lock wait times out, the in-flight flush is left to finish. At least one span request is attempted after acquiring the lock, even with no budget left; retriable failures are retried after backoff while budget remains, with one last attempt at the deadline. Each span request is bounded by the client's ``timeout`` in seconds, and the last request is not cut short. This is therefore not a strict wall-clock limit for the whole call. With ``None``, a retriable span failure is left for a later flush rather than retried within this call.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name', distinct_id='user_id')\n# Before a serverless invocation returns; keep the shared client open.\nposthog.flush(timeout_seconds=10)" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nruntime = posthog.get_feature_flag_evaluation_runtime(\"my-flag\")\nif runtime is FeatureFlagEvaluationRuntime.SERVER:\n ..." - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate. A flag set to ``FeatureFlagEvaluationRuntime.ALL`` suits either runtime, so it is returned for ``CLIENT`` and for ``SERVER``, and asking for ``ALL`` returns every loaded flag. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "The runtime to match, as a ``FeatureFlagEvaluationRuntime`` or its string value.", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nclient_keys = posthog.get_feature_flag_keys_by_evaluation_runtime(\n FeatureFlagEvaluationRuntime.CLIENT\n)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user, preserving valid serialized JSON.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Optional[str]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team'). Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and end the consumer threads. Do not use directly, call `shutdown()` instead. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Attempt final delivery and permanently shut down the client. Call this for final process cleanup or when disposing of a client that will not be reused. It closes capture lanes, stops background workers and the feature flag poller, and tears down integrations. Do not call it at the end of each request or serverless invocation when the client is shared; call ``flush()`` before returning instead. A shut-down client cannot be reused; create a new client if needed. Normally this method blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Event draining has no timeout. Queued spans get one final flush with up to 30 seconds waiting for an in-flight flush, then a fresh 30-second drain budget; the last HTTP request is not cut short. Any spans it cannot send are discarded with a warning, as are spans still open. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. When called directly from an SDK callback such as ``on_error``, shutdown is deferred to avoid blocking the worker that invoked the callback. If the callback must coordinate a blocking shutdown, have it signal an application-owned thread and return before that thread calls shutdown. Do not wait inside the callback for another thread or task that calls a lifecycle method.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span. A forked child starts with no active span; pass the parent span to continue a trace across a fork.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog = Posthog(\"\", traces={\"service_name\": \"checkout-api\"})\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is delivered on an isolated queue with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name, normally one of the `$ai_*` event names. **kwargs: Same optional arguments as `capture()`.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import capture_ai\n\nuuid = capture_ai(\n \"$ai_generation\",\n distinct_id=\"user_123\",\n properties={\"$ai_model\": \"gpt-5\"},\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip. Overriding reserved exception properties through ``properties`` is deprecated and will stop working in the next major version.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation and omit flags that cannot be evaluated locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is ``True``. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Attempt immediate delivery of queued events and ended spans, keeping the global client reusable. Call ``flush()`` before a short-lived request or serverless invocation returns when using the shared module-level client. Use ``shutdown()`` only for final process cleanup or a client that will not be reused. Flush does not stop the background workers or feature flag poller, and does not end open spans. Returning does not guarantee server receipt: pending work can remain after a timeout or span export failure, and failed events may be dropped by consumers. Calls made directly from SDK callbacks such as ``on_error`` are deferred rather than blocking the worker that invoked the callback.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Seconds to wait for event queues to drain, shared across event lanes. Defaults to 10 seconds. Pass ``None`` to wait without a time limit; this does not guarantee successful delivery. Queued spans flush concurrently, waiting up to this many seconds for an in-flight flush before starting a fresh drain budget. A lock wait timeout leaves the in-flight flush to finish. At least one span request is attempted after acquiring the lock, even with no budget left; retriable failures are retried after backoff while budget remains, with one last attempt at the deadline. The last span request is not cut short and is bounded by the client's ``timeout`` in seconds, so this is not a strict wall-clock limit for the whole call. With ``None``, a retriable span failure is left for a later flush rather than retried within this call.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "import posthog\nposthog.capture('event_name', distinct_id='user_id')\n# Before a serverless invocation returns; keep the global client open.\nposthog.flush(timeout_seconds=10)" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "Reads the `evaluation_runtime` each flag definition carries, so no extra request is made. Returns `None` when local evaluation has not loaded a definition for this key. A definition that carries no runtime reports `FeatureFlagEvaluationRuntime.ALL`, the default PostHog applies.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_evaluation_runtime\nruntime = get_feature_flag_evaluation_runtime(\"my-flag\")" - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate.", - "details": "A flag set to `FeatureFlagEvaluationRuntime.ALL` suits either runtime, so it is returned for `CLIENT` and for `SERVER`. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_keys_by_evaluation_runtime\nclient_keys = get_feature_flag_keys_by_evaluation_runtime(FeatureFlagEvaluationRuntime.CLIENT)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and stop the client's background workers. Use `shutdown()` directly in most cases. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Attempt final delivery and permanently shut down the global client. Call this for final process cleanup, not at the end of each request or serverless invocation that shares the module-level client. Use ``flush()`` before returning from those invocations instead. Shutdown closes capture lanes, stops background workers and the feature flag poller, and tears down integrations. The global client is not recreated automatically after shutdown. This normally blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Event draining has no timeout. Queued spans get a final flush with up to 30 seconds waiting for an in-flight flush, then a fresh 30-second drain budget; the last HTTP request is not cut short. Unsent queued spans and still-open spans are discarded with a warning. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. Calls made directly from SDK callbacks such as ``on_error`` are deferred to avoid deadlocking the worker. If blocking completion is required, signal an application-owned thread, return from the callback, and call ``shutdown()`` from that thread. Do not wait inside a callback for another thread or task calling a lifecycle method.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "import posthog\nposthog.traces = {\"service_name\": \"checkout-api\"}\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Tracing", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.75.6.json b/references/posthog-python-references-7.75.6.json deleted file mode 100644 index ecbda11e3..000000000 --- a/references/posthog-python-references-7.75.6.json +++ /dev/null @@ -1,3548 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.75.6", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "float" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "float" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "enable_full_ai_capture", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_trace_context", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "traces", - "description": "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.", - "isOptional": true, - "type": "dict" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to. Falls back to the context distinct ID; the call is dropped with a warning if neither is available.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is queued on an isolated AI lane with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is True. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Attempt immediate delivery of queued events and ended spans, keeping the client reusable. For a client shared across requests or serverless invocations (including the module-level client), call ``flush()`` before a short-lived invocation returns. Use ``shutdown()`` instead only for final process cleanup or when disposing of a client that will not be reused. Flush does not stop the background workers or feature flag poller, and does not end open spans. Returning does not guarantee server receipt: pending work can remain after a timeout or span export failure, and failed events may be dropped by the consumers. Calls made directly from SDK callbacks such as ``on_error`` are deferred rather than blocking the worker that invoked the callback.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Seconds to wait for event queues to drain, shared across event lanes. Defaults to 10 seconds. Pass ``None`` to wait without a time limit; this does not guarantee successful delivery. Queued spans flush concurrently. The span exporter waits up to this many seconds for an in-flight flush, then uses a fresh drain budget once it acquires the lock. If the lock wait times out, the in-flight flush is left to finish. At least one span request is attempted after acquiring the lock, even with no budget left; retriable failures are retried after backoff while budget remains, with one last attempt at the deadline. Each span request is bounded by the client's ``timeout`` in seconds, and the last request is not cut short. This is therefore not a strict wall-clock limit for the whole call. With ``None``, a retriable span failure is left for a later flush rather than retried within this call.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name', distinct_id='user_id')\n# Before a serverless invocation returns; keep the shared client open.\nposthog.flush(timeout_seconds=10)" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nruntime = posthog.get_feature_flag_evaluation_runtime(\"my-flag\")\nif runtime is FeatureFlagEvaluationRuntime.SERVER:\n ..." - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate. A flag set to ``FeatureFlagEvaluationRuntime.ALL`` suits either runtime, so it is returned for ``CLIENT`` and for ``SERVER``, and asking for ``ALL`` returns every loaded flag. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "The runtime to match, as a ``FeatureFlagEvaluationRuntime`` or its string value.", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nclient_keys = posthog.get_feature_flag_keys_by_evaluation_runtime(\n FeatureFlagEvaluationRuntime.CLIENT\n)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user, preserving valid serialized JSON.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Optional[str]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team'). Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and end the consumer threads. Do not use directly, call `shutdown()` instead. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Attempt final delivery and permanently shut down the client. Call this for final process cleanup or when disposing of a client that will not be reused. It closes capture lanes, stops background workers and the feature flag poller, and tears down integrations. Do not call it at the end of each request or serverless invocation when the client is shared; call ``flush()`` before returning instead. A shut-down client cannot be reused; create a new client if needed. Normally this method blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Event draining has no timeout. Queued spans get one final flush with up to 30 seconds waiting for an in-flight flush, then a fresh 30-second drain budget; the last HTTP request is not cut short. Any spans it cannot send are discarded with a warning, as are spans still open. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. When called directly from an SDK callback such as ``on_error``, shutdown is deferred to avoid blocking the worker that invoked the callback. If the callback must coordinate a blocking shutdown, have it signal an application-owned thread and return before that thread calls shutdown. Do not wait inside the callback for another thread or task that calls a lifecycle method.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span. A forked child starts with no active span; pass the parent span to continue a trace across a fork.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog = Posthog(\"\", traces={\"service_name\": \"checkout-api\"})\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is delivered on an isolated queue with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name, normally one of the `$ai_*` event names. **kwargs: Same optional arguments as `capture()`.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import capture_ai\n\nuuid = capture_ai(\n \"$ai_generation\",\n distinct_id=\"user_123\",\n properties={\"$ai_model\": \"gpt-5\"},\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip. Overriding reserved exception properties through ``properties`` is deprecated and will stop working in the next major version.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation and omit flags that cannot be evaluated locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is ``True``. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Attempt immediate delivery of queued events and ended spans, keeping the global client reusable. Call ``flush()`` before a short-lived request or serverless invocation returns when using the shared module-level client. Use ``shutdown()`` only for final process cleanup or a client that will not be reused. Flush does not stop the background workers or feature flag poller, and does not end open spans. Returning does not guarantee server receipt: pending work can remain after a timeout or span export failure, and failed events may be dropped by consumers. Calls made directly from SDK callbacks such as ``on_error`` are deferred rather than blocking the worker that invoked the callback.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Seconds to wait for event queues to drain, shared across event lanes. Defaults to 10 seconds. Pass ``None`` to wait without a time limit; this does not guarantee successful delivery. Queued spans flush concurrently, waiting up to this many seconds for an in-flight flush before starting a fresh drain budget. A lock wait timeout leaves the in-flight flush to finish. At least one span request is attempted after acquiring the lock, even with no budget left; retriable failures are retried after backoff while budget remains, with one last attempt at the deadline. The last span request is not cut short and is bounded by the client's ``timeout`` in seconds, so this is not a strict wall-clock limit for the whole call. With ``None``, a retriable span failure is left for a later flush rather than retried within this call.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "import posthog\nposthog.capture('event_name', distinct_id='user_id')\n# Before a serverless invocation returns; keep the global client open.\nposthog.flush(timeout_seconds=10)" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "Reads the `evaluation_runtime` each flag definition carries, so no extra request is made. Returns `None` when local evaluation has not loaded a definition for this key. A definition that carries no runtime reports `FeatureFlagEvaluationRuntime.ALL`, the default PostHog applies.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_evaluation_runtime\nruntime = get_feature_flag_evaluation_runtime(\"my-flag\")" - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate.", - "details": "A flag set to `FeatureFlagEvaluationRuntime.ALL` suits either runtime, so it is returned for `CLIENT` and for `SERVER`. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_keys_by_evaluation_runtime\nclient_keys = get_feature_flag_keys_by_evaluation_runtime(FeatureFlagEvaluationRuntime.CLIENT)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and stop the client's background workers. Use `shutdown()` directly in most cases. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Attempt final delivery and permanently shut down the global client. Call this for final process cleanup, not at the end of each request or serverless invocation that shares the module-level client. Use ``flush()`` before returning from those invocations instead. Shutdown closes capture lanes, stops background workers and the feature flag poller, and tears down integrations. The global client is not recreated automatically after shutdown. This normally blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Event draining has no timeout. Queued spans get a final flush with up to 30 seconds waiting for an in-flight flush, then a fresh 30-second drain budget; the last HTTP request is not cut short. Unsent queued spans and still-open spans are discarded with a warning. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. Calls made directly from SDK callbacks such as ``on_error`` are deferred to avoid deadlocking the worker. If blocking completion is required, signal an application-owned thread, return from the callback, and call ``shutdown()`` from that thread. Do not wait inside a callback for another thread or task calling a lifecycle method.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "import posthog\nposthog.traces = {\"service_name\": \"checkout-api\"}\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Tracing", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.75.7.json b/references/posthog-python-references-7.75.7.json deleted file mode 100644 index e6b6c343b..000000000 --- a/references/posthog-python-references-7.75.7.json +++ /dev/null @@ -1,3548 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.75.7", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "float" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "float" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "enable_full_ai_capture", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_trace_context", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "traces", - "description": "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.", - "isOptional": true, - "type": "dict" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to. Falls back to the context distinct ID; the call is dropped with a warning if neither is available.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is queued on an isolated AI lane with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is True. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Attempt immediate delivery of queued events and ended spans, keeping the client reusable. For a client shared across requests or serverless invocations (including the module-level client), call ``flush()`` before a short-lived invocation returns. Use ``shutdown()`` instead only for final process cleanup or when disposing of a client that will not be reused. Flush does not stop the background workers or feature flag poller, and does not end open spans. Returning does not guarantee server receipt: pending work can remain after a timeout or span export failure, and failed events may be dropped by the consumers. Calls made directly from SDK callbacks such as ``on_error`` are deferred rather than blocking the worker that invoked the callback.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Seconds to wait for event queues to drain, shared across event lanes. Defaults to 10 seconds. Pass ``None`` to wait without a time limit; this does not guarantee successful delivery. Queued spans flush concurrently. The span exporter waits up to this many seconds for an in-flight flush, then uses a fresh drain budget once it acquires the lock. If the lock wait times out, the in-flight flush is left to finish. At least one span request is attempted after acquiring the lock, even with no budget left; retriable failures are retried after backoff while budget remains, with one last attempt at the deadline. Each span request is bounded by the client's ``timeout`` in seconds, and the last request is not cut short. This is therefore not a strict wall-clock limit for the whole call. With ``None``, a retriable span failure is left for a later flush rather than retried within this call.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name', distinct_id='user_id')\n# Before a serverless invocation returns; keep the shared client open.\nposthog.flush(timeout_seconds=10)" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nruntime = posthog.get_feature_flag_evaluation_runtime(\"my-flag\")\nif runtime is FeatureFlagEvaluationRuntime.SERVER:\n ..." - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate. A flag set to ``FeatureFlagEvaluationRuntime.ALL`` suits either runtime, so it is returned for ``CLIENT`` and for ``SERVER``, and asking for ``ALL`` returns every loaded flag. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "The runtime to match, as a ``FeatureFlagEvaluationRuntime`` or its string value.", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nclient_keys = posthog.get_feature_flag_keys_by_evaluation_runtime(\n FeatureFlagEvaluationRuntime.CLIENT\n)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user, preserving valid serialized JSON.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Optional[str]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team'). Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and end the consumer threads. Do not use directly, call `shutdown()` instead. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Attempt final delivery and permanently shut down the client. Call this for final process cleanup or when disposing of a client that will not be reused. It closes capture lanes, stops background workers and the feature flag poller, and tears down integrations. Do not call it at the end of each request or serverless invocation when the client is shared; call ``flush()`` before returning instead. A shut-down client cannot be reused; create a new client if needed. Normally this method blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Event draining has no timeout. Queued spans get one final flush with up to 30 seconds waiting for an in-flight flush, then a fresh 30-second drain budget; the last HTTP request is not cut short. Any spans it cannot send are discarded with a warning, as are spans still open. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. When called directly from an SDK callback such as ``on_error``, shutdown is deferred to avoid blocking the worker that invoked the callback. If the callback must coordinate a blocking shutdown, have it signal an application-owned thread and return before that thread calls shutdown. Do not wait inside the callback for another thread or task that calls a lifecycle method.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span. A forked child starts with no active span; pass the parent span to continue a trace across a fork.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog = Posthog(\"\", traces={\"service_name\": \"checkout-api\"})\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is delivered on an isolated queue with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name, normally one of the `$ai_*` event names. **kwargs: Same optional arguments as `capture()`.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import capture_ai\n\nuuid = capture_ai(\n \"$ai_generation\",\n distinct_id=\"user_123\",\n properties={\"$ai_model\": \"gpt-5\"},\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip. Overriding reserved exception properties through ``properties`` is deprecated and will stop working in the next major version.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation and omit flags that cannot be evaluated locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is ``True``. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Attempt immediate delivery of queued events and ended spans, keeping the global client reusable. Call ``flush()`` before a short-lived request or serverless invocation returns when using the shared module-level client. Use ``shutdown()`` only for final process cleanup or a client that will not be reused. Flush does not stop the background workers or feature flag poller, and does not end open spans. Returning does not guarantee server receipt: pending work can remain after a timeout or span export failure, and failed events may be dropped by consumers. Calls made directly from SDK callbacks such as ``on_error`` are deferred rather than blocking the worker that invoked the callback.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Seconds to wait for event queues to drain, shared across event lanes. Defaults to 10 seconds. Pass ``None`` to wait without a time limit; this does not guarantee successful delivery. Queued spans flush concurrently, waiting up to this many seconds for an in-flight flush before starting a fresh drain budget. A lock wait timeout leaves the in-flight flush to finish. At least one span request is attempted after acquiring the lock, even with no budget left; retriable failures are retried after backoff while budget remains, with one last attempt at the deadline. The last span request is not cut short and is bounded by the client's ``timeout`` in seconds, so this is not a strict wall-clock limit for the whole call. With ``None``, a retriable span failure is left for a later flush rather than retried within this call.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "import posthog\nposthog.capture('event_name', distinct_id='user_id')\n# Before a serverless invocation returns; keep the global client open.\nposthog.flush(timeout_seconds=10)" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "Reads the `evaluation_runtime` each flag definition carries, so no extra request is made. Returns `None` when local evaluation has not loaded a definition for this key. A definition that carries no runtime reports `FeatureFlagEvaluationRuntime.ALL`, the default PostHog applies.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_evaluation_runtime\nruntime = get_feature_flag_evaluation_runtime(\"my-flag\")" - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate.", - "details": "A flag set to `FeatureFlagEvaluationRuntime.ALL` suits either runtime, so it is returned for `CLIENT` and for `SERVER`. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_keys_by_evaluation_runtime\nclient_keys = get_feature_flag_keys_by_evaluation_runtime(FeatureFlagEvaluationRuntime.CLIENT)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and stop the client's background workers. Use `shutdown()` directly in most cases. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Attempt final delivery and permanently shut down the global client. Call this for final process cleanup, not at the end of each request or serverless invocation that shares the module-level client. Use ``flush()`` before returning from those invocations instead. Shutdown closes capture lanes, stops background workers and the feature flag poller, and tears down integrations. The global client is not recreated automatically after shutdown. This normally blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Event draining has no timeout. Queued spans get a final flush with up to 30 seconds waiting for an in-flight flush, then a fresh 30-second drain budget; the last HTTP request is not cut short. Unsent queued spans and still-open spans are discarded with a warning. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. Calls made directly from SDK callbacks such as ``on_error`` are deferred to avoid deadlocking the worker. If blocking completion is required, signal an application-owned thread, return from the callback, and call ``shutdown()`` from that thread. Do not wait inside a callback for another thread or task calling a lifecycle method.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "import posthog\nposthog.traces = {\"service_name\": \"checkout-api\"}\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Tracing", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.75.8.json b/references/posthog-python-references-7.75.8.json deleted file mode 100644 index bacd9eaf2..000000000 --- a/references/posthog-python-references-7.75.8.json +++ /dev/null @@ -1,3548 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.75.8", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "float" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "float" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "enable_full_ai_capture", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_trace_context", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "traces", - "description": "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.", - "isOptional": true, - "type": "dict" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to. Falls back to the context distinct ID; the call is dropped with a warning if neither is available.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is queued on an isolated AI lane with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is True. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Attempt immediate delivery of queued events and ended spans, keeping the client reusable. For a client shared across requests or serverless invocations (including the module-level client), call ``flush()`` before a short-lived invocation returns. Use ``shutdown()`` instead only for final process cleanup or when disposing of a client that will not be reused. Flush does not stop the background workers or feature flag poller, and does not end open spans. Returning does not guarantee server receipt: pending work can remain after a timeout or span export failure, and failed events may be dropped by the consumers. Calls made directly from SDK callbacks such as ``on_error`` are deferred rather than blocking the worker that invoked the callback.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Seconds to wait for event queues to drain, shared across event lanes. Defaults to 10 seconds. Pass ``None`` to wait without a time limit; this does not guarantee successful delivery. Queued spans flush concurrently. The span exporter waits up to this many seconds for an in-flight flush, then uses a fresh drain budget once it acquires the lock. If the lock wait times out, the in-flight flush is left to finish. At least one span request is attempted after acquiring the lock, even with no budget left; retriable failures are retried after backoff while budget remains, with one last attempt at the deadline. Each span request is bounded by the client's ``timeout`` in seconds, and the last request is not cut short. This is therefore not a strict wall-clock limit for the whole call. With ``None``, a retriable span failure is left for a later flush rather than retried within this call.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name', distinct_id='user_id')\n# Before a serverless invocation returns; keep the shared client open.\nposthog.flush(timeout_seconds=10)" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nruntime = posthog.get_feature_flag_evaluation_runtime(\"my-flag\")\nif runtime is FeatureFlagEvaluationRuntime.SERVER:\n ..." - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate. A flag set to ``FeatureFlagEvaluationRuntime.ALL`` suits either runtime, so it is returned for ``CLIENT`` and for ``SERVER``, and asking for ``ALL`` returns every loaded flag. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "The runtime to match, as a ``FeatureFlagEvaluationRuntime`` or its string value.", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nclient_keys = posthog.get_feature_flag_keys_by_evaluation_runtime(\n FeatureFlagEvaluationRuntime.CLIENT\n)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user, preserving valid serialized JSON.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Optional[str]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team'). Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and end the consumer threads. Do not use directly, call `shutdown()` instead. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Attempt final delivery and permanently shut down the client. Call this for final process cleanup or when disposing of a client that will not be reused. It closes capture lanes, stops background workers and the feature flag poller, and tears down integrations. Do not call it at the end of each request or serverless invocation when the client is shared; call ``flush()`` before returning instead. A shut-down client cannot be reused; create a new client if needed. Normally this method blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Event draining has no timeout. Queued spans get one final flush with up to 30 seconds waiting for an in-flight flush, then a fresh 30-second drain budget; the last HTTP request is not cut short. Any spans it cannot send are discarded with a warning, as are spans still open. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. When called directly from an SDK callback such as ``on_error``, shutdown is deferred to avoid blocking the worker that invoked the callback. If the callback must coordinate a blocking shutdown, have it signal an application-owned thread and return before that thread calls shutdown. Do not wait inside the callback for another thread or task that calls a lifecycle method.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span. A forked child starts with no active span; pass the parent span to continue a trace across a fork.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog = Posthog(\"\", traces={\"service_name\": \"checkout-api\"})\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is delivered on an isolated queue with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name, normally one of the `$ai_*` event names. **kwargs: Same optional arguments as `capture()`.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import capture_ai\n\nuuid = capture_ai(\n \"$ai_generation\",\n distinct_id=\"user_123\",\n properties={\"$ai_model\": \"gpt-5\"},\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip. Overriding reserved exception properties through ``properties`` is deprecated and will stop working in the next major version.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation and omit flags that cannot be evaluated locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is ``True``. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Attempt immediate delivery of queued events and ended spans, keeping the global client reusable. Call ``flush()`` before a short-lived request or serverless invocation returns when using the shared module-level client. Use ``shutdown()`` only for final process cleanup or a client that will not be reused. Flush does not stop the background workers or feature flag poller, and does not end open spans. Returning does not guarantee server receipt: pending work can remain after a timeout or span export failure, and failed events may be dropped by consumers. Calls made directly from SDK callbacks such as ``on_error`` are deferred rather than blocking the worker that invoked the callback.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Seconds to wait for event queues to drain, shared across event lanes. Defaults to 10 seconds. Pass ``None`` to wait without a time limit; this does not guarantee successful delivery. Queued spans flush concurrently, waiting up to this many seconds for an in-flight flush before starting a fresh drain budget. A lock wait timeout leaves the in-flight flush to finish. At least one span request is attempted after acquiring the lock, even with no budget left; retriable failures are retried after backoff while budget remains, with one last attempt at the deadline. The last span request is not cut short and is bounded by the client's ``timeout`` in seconds, so this is not a strict wall-clock limit for the whole call. With ``None``, a retriable span failure is left for a later flush rather than retried within this call.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "import posthog\nposthog.capture('event_name', distinct_id='user_id')\n# Before a serverless invocation returns; keep the global client open.\nposthog.flush(timeout_seconds=10)" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "Reads the `evaluation_runtime` each flag definition carries, so no extra request is made. Returns `None` when local evaluation has not loaded a definition for this key. A definition that carries no runtime reports `FeatureFlagEvaluationRuntime.ALL`, the default PostHog applies.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_evaluation_runtime\nruntime = get_feature_flag_evaluation_runtime(\"my-flag\")" - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate.", - "details": "A flag set to `FeatureFlagEvaluationRuntime.ALL` suits either runtime, so it is returned for `CLIENT` and for `SERVER`. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_keys_by_evaluation_runtime\nclient_keys = get_feature_flag_keys_by_evaluation_runtime(FeatureFlagEvaluationRuntime.CLIENT)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and stop the client's background workers. Use `shutdown()` directly in most cases. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Attempt final delivery and permanently shut down the global client. Call this for final process cleanup, not at the end of each request or serverless invocation that shares the module-level client. Use ``flush()`` before returning from those invocations instead. Shutdown closes capture lanes, stops background workers and the feature flag poller, and tears down integrations. The global client is not recreated automatically after shutdown. This normally blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Event draining has no timeout. Queued spans get a final flush with up to 30 seconds waiting for an in-flight flush, then a fresh 30-second drain budget; the last HTTP request is not cut short. Unsent queued spans and still-open spans are discarded with a warning. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. Calls made directly from SDK callbacks such as ``on_error`` are deferred to avoid deadlocking the worker. If blocking completion is required, signal an application-owned thread, return from the callback, and call ``shutdown()`` from that thread. Do not wait inside a callback for another thread or task calling a lifecycle method.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "import posthog\nposthog.traces = {\"service_name\": \"checkout-api\"}\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Tracing", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.75.9.json b/references/posthog-python-references-7.75.9.json deleted file mode 100644 index 3ced9019c..000000000 --- a/references/posthog-python-references-7.75.9.json +++ /dev/null @@ -1,3548 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.75.9", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "float" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "float" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "enable_full_ai_capture", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_trace_context", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "traces", - "description": "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.", - "isOptional": true, - "type": "dict" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to. Falls back to the context distinct ID; the call is dropped with a warning if neither is available.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is queued on an isolated AI lane with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is True. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Attempt immediate delivery of queued events and ended spans, keeping the client reusable. For a client shared across requests or serverless invocations (including the module-level client), call ``flush()`` before a short-lived invocation returns. Use ``shutdown()`` instead only for final process cleanup or when disposing of a client that will not be reused. Flush does not stop the background workers or feature flag poller, and does not end open spans. Returning does not guarantee server receipt: pending work can remain after a timeout or span export failure, and failed events may be dropped by the consumers. Calls made directly from SDK callbacks such as ``on_error`` are deferred rather than blocking the worker that invoked the callback.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Seconds to wait for event queues to drain, shared across event lanes. Defaults to 10 seconds. Pass ``None`` to wait without a time limit; this does not guarantee successful delivery. Queued spans flush concurrently. The span exporter waits up to this many seconds for an in-flight flush, then uses a fresh drain budget once it acquires the lock. If the lock wait times out, the in-flight flush is left to finish. At least one span request is attempted after acquiring the lock, even with no budget left; retriable failures are retried after backoff while budget remains, with one last attempt at the deadline. Each span request is bounded by the client's ``timeout`` in seconds, and the last request is not cut short. This is therefore not a strict wall-clock limit for the whole call. With ``None``, a retriable span failure is left for a later flush rather than retried within this call.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name', distinct_id='user_id')\n# Before a serverless invocation returns; keep the shared client open.\nposthog.flush(timeout_seconds=10)" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nruntime = posthog.get_feature_flag_evaluation_runtime(\"my-flag\")\nif runtime is FeatureFlagEvaluationRuntime.SERVER:\n ..." - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate. A flag set to ``FeatureFlagEvaluationRuntime.ALL`` suits either runtime, so it is returned for ``CLIENT`` and for ``SERVER``, and asking for ``ALL`` returns every loaded flag. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "The runtime to match, as a ``FeatureFlagEvaluationRuntime`` or its string value.", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nclient_keys = posthog.get_feature_flag_keys_by_evaluation_runtime(\n FeatureFlagEvaluationRuntime.CLIENT\n)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user, preserving valid serialized JSON.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Optional[str]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team'). Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and end the consumer threads. Do not use directly, call `shutdown()` instead. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Attempt final delivery and permanently shut down the client. Call this for final process cleanup or when disposing of a client that will not be reused. It closes capture lanes, stops background workers and the feature flag poller, and tears down integrations. Do not call it at the end of each request or serverless invocation when the client is shared; call ``flush()`` before returning instead. A shut-down client cannot be reused; create a new client if needed. Normally this method blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Event draining has no timeout. Queued spans get one final flush with up to 30 seconds waiting for an in-flight flush, then a fresh 30-second drain budget; the last HTTP request is not cut short. Any spans it cannot send are discarded with a warning, as are spans still open. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. When called directly from an SDK callback such as ``on_error``, shutdown is deferred to avoid blocking the worker that invoked the callback. If the callback must coordinate a blocking shutdown, have it signal an application-owned thread and return before that thread calls shutdown. Do not wait inside the callback for another thread or task that calls a lifecycle method.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span. A forked child starts with no active span; pass the parent span to continue a trace across a fork.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog = Posthog(\"\", traces={\"service_name\": \"checkout-api\"})\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is delivered on an isolated queue with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name, normally one of the `$ai_*` event names. **kwargs: Same optional arguments as `capture()`.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import capture_ai\n\nuuid = capture_ai(\n \"$ai_generation\",\n distinct_id=\"user_123\",\n properties={\"$ai_model\": \"gpt-5\"},\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip. Overriding reserved exception properties through ``properties`` is deprecated and will stop working in the next major version.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation and omit flags that cannot be evaluated locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is ``True``. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Attempt immediate delivery of queued events and ended spans, keeping the global client reusable. Call ``flush()`` before a short-lived request or serverless invocation returns when using the shared module-level client. Use ``shutdown()`` only for final process cleanup or a client that will not be reused. Flush does not stop the background workers or feature flag poller, and does not end open spans. Returning does not guarantee server receipt: pending work can remain after a timeout or span export failure, and failed events may be dropped by consumers. Calls made directly from SDK callbacks such as ``on_error`` are deferred rather than blocking the worker that invoked the callback.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Seconds to wait for event queues to drain, shared across event lanes. Defaults to 10 seconds. Pass ``None`` to wait without a time limit; this does not guarantee successful delivery. Queued spans flush concurrently, waiting up to this many seconds for an in-flight flush before starting a fresh drain budget. A lock wait timeout leaves the in-flight flush to finish. At least one span request is attempted after acquiring the lock, even with no budget left; retriable failures are retried after backoff while budget remains, with one last attempt at the deadline. The last span request is not cut short and is bounded by the client's ``timeout`` in seconds, so this is not a strict wall-clock limit for the whole call. With ``None``, a retriable span failure is left for a later flush rather than retried within this call.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "import posthog\nposthog.capture('event_name', distinct_id='user_id')\n# Before a serverless invocation returns; keep the global client open.\nposthog.flush(timeout_seconds=10)" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "Reads the `evaluation_runtime` each flag definition carries, so no extra request is made. Returns `None` when local evaluation has not loaded a definition for this key. A definition that carries no runtime reports `FeatureFlagEvaluationRuntime.ALL`, the default PostHog applies.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_evaluation_runtime\nruntime = get_feature_flag_evaluation_runtime(\"my-flag\")" - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate.", - "details": "A flag set to `FeatureFlagEvaluationRuntime.ALL` suits either runtime, so it is returned for `CLIENT` and for `SERVER`. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_keys_by_evaluation_runtime\nclient_keys = get_feature_flag_keys_by_evaluation_runtime(FeatureFlagEvaluationRuntime.CLIENT)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and stop the client's background workers. Use `shutdown()` directly in most cases. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Attempt final delivery and permanently shut down the global client. Call this for final process cleanup, not at the end of each request or serverless invocation that shares the module-level client. Use ``flush()`` before returning from those invocations instead. Shutdown closes capture lanes, stops background workers and the feature flag poller, and tears down integrations. The global client is not recreated automatically after shutdown. This normally blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Event draining has no timeout. Queued spans get a final flush with up to 30 seconds waiting for an in-flight flush, then a fresh 30-second drain budget; the last HTTP request is not cut short. Unsent queued spans and still-open spans are discarded with a warning. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. Calls made directly from SDK callbacks such as ``on_error`` are deferred to avoid deadlocking the worker. If blocking completion is required, signal an application-owned thread, return from the callback, and call ``shutdown()`` from that thread. Do not wait inside a callback for another thread or task calling a lifecycle method.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "import posthog\nposthog.traces = {\"service_name\": \"checkout-api\"}\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Tracing", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.76.0.json b/references/posthog-python-references-7.76.0.json deleted file mode 100644 index 9df82cc58..000000000 --- a/references/posthog-python-references-7.76.0.json +++ /dev/null @@ -1,3548 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.76.0", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "float" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "float" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "enable_full_ai_capture", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_trace_context", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "traces", - "description": "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.", - "isOptional": true, - "type": "dict" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to. Falls back to the context distinct ID; the call is dropped with a warning if neither is available.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is queued on an isolated AI lane with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is True. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Attempt immediate delivery of queued events and ended spans, keeping the client reusable. For a client shared across requests or serverless invocations (including the module-level client), call ``flush()`` before a short-lived invocation returns. Use ``shutdown()`` instead only for final process cleanup or when disposing of a client that will not be reused. Flush does not stop the background workers or feature flag poller, and does not end open spans. Returning does not guarantee server receipt: pending work can remain after a timeout or span export failure, and failed events may be dropped by the consumers. Calls made directly from SDK callbacks such as ``on_error`` are deferred rather than blocking the worker that invoked the callback.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Seconds to wait for event queues to drain, shared across event lanes. Defaults to 10 seconds. Pass ``None`` to wait without a time limit; this does not guarantee successful delivery. Queued spans flush concurrently. The span exporter waits up to this many seconds for an in-flight flush, then uses a fresh drain budget once it acquires the lock. If the lock wait times out, the in-flight flush is left to finish. At least one span request is attempted after acquiring the lock, even with no budget left; retriable failures are retried after backoff while budget remains, with one last attempt at the deadline. Each span request is bounded by the client's ``timeout`` in seconds, and the last request is not cut short. This is therefore not a strict wall-clock limit for the whole call. With ``None``, a retriable span failure is left for a later flush rather than retried within this call.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name', distinct_id='user_id')\n# Before a serverless invocation returns; keep the shared client open.\nposthog.flush(timeout_seconds=10)" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nruntime = posthog.get_feature_flag_evaluation_runtime(\"my-flag\")\nif runtime is FeatureFlagEvaluationRuntime.SERVER:\n ..." - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate. A flag set to ``FeatureFlagEvaluationRuntime.ALL`` suits either runtime, so it is returned for ``CLIENT`` and for ``SERVER``, and asking for ``ALL`` returns every loaded flag. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "The runtime to match, as a ``FeatureFlagEvaluationRuntime`` or its string value.", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nclient_keys = posthog.get_feature_flag_keys_by_evaluation_runtime(\n FeatureFlagEvaluationRuntime.CLIENT\n)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user, preserving valid serialized JSON.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Optional[str]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team'). Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and end the consumer threads. Do not use directly, call `shutdown()` instead. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Attempt final delivery and permanently shut down the client. Call this for final process cleanup or when disposing of a client that will not be reused. It closes capture lanes, stops background workers and the feature flag poller, and tears down integrations. Do not call it at the end of each request or serverless invocation when the client is shared; call ``flush()`` before returning instead. A shut-down client cannot be reused; create a new client if needed. Normally this method blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Event draining has no timeout. Queued spans get one final flush with up to 30 seconds waiting for an in-flight flush, then a fresh 30-second drain budget; the last HTTP request is not cut short. Any spans it cannot send are discarded with a warning, as are spans still open. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. When called directly from an SDK callback such as ``on_error``, shutdown is deferred to avoid blocking the worker that invoked the callback. If the callback must coordinate a blocking shutdown, have it signal an application-owned thread and return before that thread calls shutdown. Do not wait inside the callback for another thread or task that calls a lifecycle method.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span. A forked child starts with no active span; pass the parent span to continue a trace across a fork.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog = Posthog(\"\", traces={\"service_name\": \"checkout-api\"})\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is delivered on an isolated queue with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name, normally one of the `$ai_*` event names. **kwargs: Same optional arguments as `capture()`.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import capture_ai\n\nuuid = capture_ai(\n \"$ai_generation\",\n distinct_id=\"user_123\",\n properties={\"$ai_model\": \"gpt-5\"},\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip. Overriding reserved exception properties through ``properties`` is deprecated and will stop working in the next major version.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation and omit flags that cannot be evaluated locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is ``True``. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Attempt immediate delivery of queued events and ended spans, keeping the global client reusable. Call ``flush()`` before a short-lived request or serverless invocation returns when using the shared module-level client. Use ``shutdown()`` only for final process cleanup or a client that will not be reused. Flush does not stop the background workers or feature flag poller, and does not end open spans. Returning does not guarantee server receipt: pending work can remain after a timeout or span export failure, and failed events may be dropped by consumers. Calls made directly from SDK callbacks such as ``on_error`` are deferred rather than blocking the worker that invoked the callback.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Seconds to wait for event queues to drain, shared across event lanes. Defaults to 10 seconds. Pass ``None`` to wait without a time limit; this does not guarantee successful delivery. Queued spans flush concurrently, waiting up to this many seconds for an in-flight flush before starting a fresh drain budget. A lock wait timeout leaves the in-flight flush to finish. At least one span request is attempted after acquiring the lock, even with no budget left; retriable failures are retried after backoff while budget remains, with one last attempt at the deadline. The last span request is not cut short and is bounded by the client's ``timeout`` in seconds, so this is not a strict wall-clock limit for the whole call. With ``None``, a retriable span failure is left for a later flush rather than retried within this call.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "import posthog\nposthog.capture('event_name', distinct_id='user_id')\n# Before a serverless invocation returns; keep the global client open.\nposthog.flush(timeout_seconds=10)" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "Reads the `evaluation_runtime` each flag definition carries, so no extra request is made. Returns `None` when local evaluation has not loaded a definition for this key. A definition that carries no runtime reports `FeatureFlagEvaluationRuntime.ALL`, the default PostHog applies.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_evaluation_runtime\nruntime = get_feature_flag_evaluation_runtime(\"my-flag\")" - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate.", - "details": "A flag set to `FeatureFlagEvaluationRuntime.ALL` suits either runtime, so it is returned for `CLIENT` and for `SERVER`. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_keys_by_evaluation_runtime\nclient_keys = get_feature_flag_keys_by_evaluation_runtime(FeatureFlagEvaluationRuntime.CLIENT)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and stop the client's background workers. Use `shutdown()` directly in most cases. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Attempt final delivery and permanently shut down the global client. Call this for final process cleanup, not at the end of each request or serverless invocation that shares the module-level client. Use ``flush()`` before returning from those invocations instead. Shutdown closes capture lanes, stops background workers and the feature flag poller, and tears down integrations. The global client is not recreated automatically after shutdown. This normally blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Event draining has no timeout. Queued spans get a final flush with up to 30 seconds waiting for an in-flight flush, then a fresh 30-second drain budget; the last HTTP request is not cut short. Unsent queued spans and still-open spans are discarded with a warning. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. Calls made directly from SDK callbacks such as ``on_error`` are deferred to avoid deadlocking the worker. If blocking completion is required, signal an application-owned thread, return from the callback, and call ``shutdown()`` from that thread. Do not wait inside a callback for another thread or task calling a lifecycle method.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "import posthog\nposthog.traces = {\"service_name\": \"checkout-api\"}\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Tracing", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.76.1.json b/references/posthog-python-references-7.76.1.json deleted file mode 100644 index 966c6f297..000000000 --- a/references/posthog-python-references-7.76.1.json +++ /dev/null @@ -1,3548 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.76.1", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "float" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "float" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "enable_full_ai_capture", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_trace_context", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "traces", - "description": "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.", - "isOptional": true, - "type": "dict" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to. Falls back to the context distinct ID; the call is dropped with a warning if neither is available.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is queued on an isolated AI lane with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is True. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Attempt immediate delivery of queued events and ended spans, keeping the client reusable. For a client shared across requests or serverless invocations (including the module-level client), call ``flush()`` before a short-lived invocation returns. Use ``shutdown()`` instead only for final process cleanup or when disposing of a client that will not be reused. Flush does not stop the background workers or feature flag poller, and does not end open spans. Returning does not guarantee server receipt: pending work can remain after a timeout or span export failure, and failed events may be dropped by the consumers. Calls made directly from SDK callbacks such as ``on_error`` are deferred rather than blocking the worker that invoked the callback.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Seconds to wait for event queues to drain, shared across event lanes. Defaults to 10 seconds. Pass ``None`` to wait without a time limit; this does not guarantee successful delivery. Queued spans flush concurrently. The span exporter waits up to this many seconds for an in-flight flush, then uses a fresh drain budget once it acquires the lock. If the lock wait times out, the in-flight flush is left to finish. At least one span request is attempted after acquiring the lock, even with no budget left; retriable failures are retried after backoff while budget remains, with one last attempt at the deadline. Each span request is bounded by the client's ``timeout`` in seconds, and the last request is not cut short. This is therefore not a strict wall-clock limit for the whole call. With ``None``, a retriable span failure is left for a later flush rather than retried within this call.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name', distinct_id='user_id')\n# Before a serverless invocation returns; keep the shared client open.\nposthog.flush(timeout_seconds=10)" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nruntime = posthog.get_feature_flag_evaluation_runtime(\"my-flag\")\nif runtime is FeatureFlagEvaluationRuntime.SERVER:\n ..." - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate. A flag set to ``FeatureFlagEvaluationRuntime.ALL`` suits either runtime, so it is returned for ``CLIENT`` and for ``SERVER``, and asking for ``ALL`` returns every loaded flag. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "The runtime to match, as a ``FeatureFlagEvaluationRuntime`` or its string value.", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nclient_keys = posthog.get_feature_flag_keys_by_evaluation_runtime(\n FeatureFlagEvaluationRuntime.CLIENT\n)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user, preserving valid serialized JSON.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Optional[str]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team'). Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and end the consumer threads. Do not use directly, call `shutdown()` instead. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Attempt final delivery and permanently shut down the client. Call this for final process cleanup or when disposing of a client that will not be reused. It closes capture lanes, stops background workers and the feature flag poller, and tears down integrations. Do not call it at the end of each request or serverless invocation when the client is shared; call ``flush()`` before returning instead. A shut-down client cannot be reused; create a new client if needed. Normally this method blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Event draining has no timeout. Queued spans get one final flush with up to 30 seconds waiting for an in-flight flush, then a fresh 30-second drain budget; the last HTTP request is not cut short. Any spans it cannot send are discarded with a warning, as are spans still open. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. When called directly from an SDK callback such as ``on_error``, shutdown is deferred to avoid blocking the worker that invoked the callback. If the callback must coordinate a blocking shutdown, have it signal an application-owned thread and return before that thread calls shutdown. Do not wait inside the callback for another thread or task that calls a lifecycle method.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span. A forked child starts with no active span; pass the parent span to continue a trace across a fork.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog = Posthog(\"\", traces={\"service_name\": \"checkout-api\"})\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is delivered on an isolated queue with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name, normally one of the `$ai_*` event names. **kwargs: Same optional arguments as `capture()`.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import capture_ai\n\nuuid = capture_ai(\n \"$ai_generation\",\n distinct_id=\"user_123\",\n properties={\"$ai_model\": \"gpt-5\"},\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip. Overriding reserved exception properties through ``properties`` is deprecated and will stop working in the next major version.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation and omit flags that cannot be evaluated locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is ``True``. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Attempt immediate delivery of queued events and ended spans, keeping the global client reusable. Call ``flush()`` before a short-lived request or serverless invocation returns when using the shared module-level client. Use ``shutdown()`` only for final process cleanup or a client that will not be reused. Flush does not stop the background workers or feature flag poller, and does not end open spans. Returning does not guarantee server receipt: pending work can remain after a timeout or span export failure, and failed events may be dropped by consumers. Calls made directly from SDK callbacks such as ``on_error`` are deferred rather than blocking the worker that invoked the callback.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Seconds to wait for event queues to drain, shared across event lanes. Defaults to 10 seconds. Pass ``None`` to wait without a time limit; this does not guarantee successful delivery. Queued spans flush concurrently, waiting up to this many seconds for an in-flight flush before starting a fresh drain budget. A lock wait timeout leaves the in-flight flush to finish. At least one span request is attempted after acquiring the lock, even with no budget left; retriable failures are retried after backoff while budget remains, with one last attempt at the deadline. The last span request is not cut short and is bounded by the client's ``timeout`` in seconds, so this is not a strict wall-clock limit for the whole call. With ``None``, a retriable span failure is left for a later flush rather than retried within this call.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "import posthog\nposthog.capture('event_name', distinct_id='user_id')\n# Before a serverless invocation returns; keep the global client open.\nposthog.flush(timeout_seconds=10)" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "Reads the `evaluation_runtime` each flag definition carries, so no extra request is made. Returns `None` when local evaluation has not loaded a definition for this key. A definition that carries no runtime reports `FeatureFlagEvaluationRuntime.ALL`, the default PostHog applies.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_evaluation_runtime\nruntime = get_feature_flag_evaluation_runtime(\"my-flag\")" - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate.", - "details": "A flag set to `FeatureFlagEvaluationRuntime.ALL` suits either runtime, so it is returned for `CLIENT` and for `SERVER`. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_keys_by_evaluation_runtime\nclient_keys = get_feature_flag_keys_by_evaluation_runtime(FeatureFlagEvaluationRuntime.CLIENT)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and stop the client's background workers. Use `shutdown()` directly in most cases. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Attempt final delivery and permanently shut down the global client. Call this for final process cleanup, not at the end of each request or serverless invocation that shares the module-level client. Use ``flush()`` before returning from those invocations instead. Shutdown closes capture lanes, stops background workers and the feature flag poller, and tears down integrations. The global client is not recreated automatically after shutdown. This normally blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Event draining has no timeout. Queued spans get a final flush with up to 30 seconds waiting for an in-flight flush, then a fresh 30-second drain budget; the last HTTP request is not cut short. Unsent queued spans and still-open spans are discarded with a warning. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. Calls made directly from SDK callbacks such as ``on_error`` are deferred to avoid deadlocking the worker. If blocking completion is required, signal an application-owned thread, return from the callback, and call ``shutdown()`` from that thread. Do not wait inside a callback for another thread or task calling a lifecycle method.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "import posthog\nposthog.traces = {\"service_name\": \"checkout-api\"}\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Tracing", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.77.0.json b/references/posthog-python-references-7.77.0.json deleted file mode 100644 index 70871253b..000000000 --- a/references/posthog-python-references-7.77.0.json +++ /dev/null @@ -1,3548 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.77.0", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "float" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "float" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "enable_full_ai_capture", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_trace_context", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "traces", - "description": "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.", - "isOptional": true, - "type": "dict" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to. Falls back to the context distinct ID; the call is dropped with a warning if neither is available.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is queued on an isolated AI lane with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is True. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Attempt immediate delivery of queued events and ended spans, keeping the client reusable. For a client shared across requests or serverless invocations (including the module-level client), call ``flush()`` before a short-lived invocation returns. Use ``shutdown()`` instead only for final process cleanup or when disposing of a client that will not be reused. Flush does not stop the background workers or feature flag poller, and does not end open spans. Returning does not guarantee server receipt: pending work can remain after a timeout or span export failure, and failed events may be dropped by the consumers. Calls made directly from SDK callbacks such as ``on_error`` are deferred rather than blocking the worker that invoked the callback.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Seconds to wait for event queues to drain, shared across event lanes. Defaults to 10 seconds. Pass ``None`` to wait without a time limit; this does not guarantee successful delivery. Queued spans flush concurrently. The span exporter waits up to this many seconds for an in-flight flush, then uses a fresh drain budget once it acquires the lock. If the lock wait times out, the in-flight flush is left to finish. At least one span request is attempted after acquiring the lock, even with no budget left; retriable failures are retried after backoff while budget remains, with one last attempt at the deadline. Each span request is bounded by the client's ``timeout`` in seconds, and the last request is not cut short. This is therefore not a strict wall-clock limit for the whole call. With ``None``, a retriable span failure is left for a later flush rather than retried within this call.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name', distinct_id='user_id')\n# Before a serverless invocation returns; keep the shared client open.\nposthog.flush(timeout_seconds=10)" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nruntime = posthog.get_feature_flag_evaluation_runtime(\"my-flag\")\nif runtime is FeatureFlagEvaluationRuntime.SERVER:\n ..." - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate. A flag set to ``FeatureFlagEvaluationRuntime.ALL`` suits either runtime, so it is returned for ``CLIENT`` and for ``SERVER``, and asking for ``ALL`` returns every loaded flag. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "The runtime to match, as a ``FeatureFlagEvaluationRuntime`` or its string value.", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nclient_keys = posthog.get_feature_flag_keys_by_evaluation_runtime(\n FeatureFlagEvaluationRuntime.CLIENT\n)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user, preserving valid serialized JSON.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Optional[str]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team'). Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and end the consumer threads. Do not use directly, call `shutdown()` instead. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Attempt final delivery and permanently shut down the client. Call this for final process cleanup or when disposing of a client that will not be reused. It closes capture lanes, stops background workers and the feature flag poller, and tears down integrations. Do not call it at the end of each request or serverless invocation when the client is shared; call ``flush()`` before returning instead. A shut-down client cannot be reused; create a new client if needed. Normally this method blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Event draining has no timeout. Queued spans get one final flush with up to 30 seconds waiting for an in-flight flush, then a fresh 30-second drain budget; the last HTTP request is not cut short. Any spans it cannot send are discarded with a warning, as are spans still open. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. When called directly from an SDK callback such as ``on_error``, shutdown is deferred to avoid blocking the worker that invoked the callback. If the callback must coordinate a blocking shutdown, have it signal an application-owned thread and return before that thread calls shutdown. Do not wait inside the callback for another thread or task that calls a lifecycle method.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span. A forked child starts with no active span; pass the parent span to continue a trace across a fork.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog = Posthog(\"\", traces={\"service_name\": \"checkout-api\"})\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is delivered on an isolated queue with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name, normally one of the `$ai_*` event names. **kwargs: Same optional arguments as `capture()`.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import capture_ai\n\nuuid = capture_ai(\n \"$ai_generation\",\n distinct_id=\"user_123\",\n properties={\"$ai_model\": \"gpt-5\"},\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip. Overriding reserved exception properties through ``properties`` is deprecated and will stop working in the next major version.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation and omit flags that cannot be evaluated locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is ``True``. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Attempt immediate delivery of queued events and ended spans, keeping the global client reusable. Call ``flush()`` before a short-lived request or serverless invocation returns when using the shared module-level client. Use ``shutdown()`` only for final process cleanup or a client that will not be reused. Flush does not stop the background workers or feature flag poller, and does not end open spans. Returning does not guarantee server receipt: pending work can remain after a timeout or span export failure, and failed events may be dropped by consumers. Calls made directly from SDK callbacks such as ``on_error`` are deferred rather than blocking the worker that invoked the callback.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Seconds to wait for event queues to drain, shared across event lanes. Defaults to 10 seconds. Pass ``None`` to wait without a time limit; this does not guarantee successful delivery. Queued spans flush concurrently, waiting up to this many seconds for an in-flight flush before starting a fresh drain budget. A lock wait timeout leaves the in-flight flush to finish. At least one span request is attempted after acquiring the lock, even with no budget left; retriable failures are retried after backoff while budget remains, with one last attempt at the deadline. The last span request is not cut short and is bounded by the client's ``timeout`` in seconds, so this is not a strict wall-clock limit for the whole call. With ``None``, a retriable span failure is left for a later flush rather than retried within this call.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "import posthog\nposthog.capture('event_name', distinct_id='user_id')\n# Before a serverless invocation returns; keep the global client open.\nposthog.flush(timeout_seconds=10)" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "Reads the `evaluation_runtime` each flag definition carries, so no extra request is made. Returns `None` when local evaluation has not loaded a definition for this key. A definition that carries no runtime reports `FeatureFlagEvaluationRuntime.ALL`, the default PostHog applies.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_evaluation_runtime\nruntime = get_feature_flag_evaluation_runtime(\"my-flag\")" - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate.", - "details": "A flag set to `FeatureFlagEvaluationRuntime.ALL` suits either runtime, so it is returned for `CLIENT` and for `SERVER`. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_keys_by_evaluation_runtime\nclient_keys = get_feature_flag_keys_by_evaluation_runtime(FeatureFlagEvaluationRuntime.CLIENT)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and stop the client's background workers. Use `shutdown()` directly in most cases. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Attempt final delivery and permanently shut down the global client. Call this for final process cleanup, not at the end of each request or serverless invocation that shares the module-level client. Use ``flush()`` before returning from those invocations instead. Shutdown closes capture lanes, stops background workers and the feature flag poller, and tears down integrations. The global client is not recreated automatically after shutdown. This normally blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Event draining has no timeout. Queued spans get a final flush with up to 30 seconds waiting for an in-flight flush, then a fresh 30-second drain budget; the last HTTP request is not cut short. Unsent queued spans and still-open spans are discarded with a warning. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. Calls made directly from SDK callbacks such as ``on_error`` are deferred to avoid deadlocking the worker. If blocking completion is required, signal an application-owned thread, return from the callback, and call ``shutdown()`` from that thread. Do not wait inside a callback for another thread or task calling a lifecycle method.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "import posthog\nposthog.traces = {\"service_name\": \"checkout-api\"}\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Tracing", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.78.0.json b/references/posthog-python-references-7.78.0.json deleted file mode 100644 index 66be86ee2..000000000 --- a/references/posthog-python-references-7.78.0.json +++ /dev/null @@ -1,3548 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.78.0", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "float" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "float" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "enable_full_ai_capture", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_trace_context", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "traces", - "description": "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.", - "isOptional": true, - "type": "dict" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to. Falls back to the context distinct ID; the call is dropped with a warning if neither is available.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is queued on an isolated AI lane with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are simply omitted from the snapshot.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is True. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Attempt immediate delivery of queued events and ended spans, keeping the client reusable. For a client shared across requests or serverless invocations (including the module-level client), call ``flush()`` before a short-lived invocation returns. Use ``shutdown()`` instead only for final process cleanup or when disposing of a client that will not be reused. Flush does not stop the background workers or feature flag poller, and does not end open spans. Returning does not guarantee server receipt: pending work can remain after a timeout or span export failure, and failed events may be dropped by the consumers. Calls made directly from SDK callbacks such as ``on_error`` are deferred rather than blocking the worker that invoked the callback.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Seconds to wait for event queues to drain, shared across event lanes. Defaults to 10 seconds. Pass ``None`` to wait without a time limit; this does not guarantee successful delivery. Queued spans flush concurrently. The span exporter waits up to this many seconds for an in-flight flush, then uses a fresh drain budget once it acquires the lock. If the lock wait times out, the in-flight flush is left to finish. At least one span request is attempted after acquiring the lock, even with no budget left; retriable failures are retried after backoff while budget remains, with one last attempt at the deadline. Each span request is bounded by the client's ``timeout`` in seconds, and the last request is not cut short. This is therefore not a strict wall-clock limit for the whole call. With ``None``, a retriable span failure is left for a later flush rather than retried within this call.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name', distinct_id='user_id')\n# Before a serverless invocation returns; keep the shared client open.\nposthog.flush(timeout_seconds=10)" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nruntime = posthog.get_feature_flag_evaluation_runtime(\"my-flag\")\nif runtime is FeatureFlagEvaluationRuntime.SERVER:\n ..." - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate. A flag set to ``FeatureFlagEvaluationRuntime.ALL`` suits either runtime, so it is returned for ``CLIENT`` and for ``SERVER``, and asking for ``ALL`` returns every loaded flag. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "The runtime to match, as a ``FeatureFlagEvaluationRuntime`` or its string value.", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nclient_keys = posthog.get_feature_flag_keys_by_evaluation_runtime(\n FeatureFlagEvaluationRuntime.CLIENT\n)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user, preserving valid serialized JSON.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Optional[str]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team'). Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and end the consumer threads. Do not use directly, call `shutdown()` instead. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Attempt final delivery and permanently shut down the client. Call this for final process cleanup or when disposing of a client that will not be reused. It closes capture lanes, stops background workers and the feature flag poller, and tears down integrations. Do not call it at the end of each request or serverless invocation when the client is shared; call ``flush()`` before returning instead. A shut-down client cannot be reused; create a new client if needed. Normally this method blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Event draining has no timeout. Queued spans get one final flush with up to 30 seconds waiting for an in-flight flush, then a fresh 30-second drain budget; the last HTTP request is not cut short. Any spans it cannot send are discarded with a warning, as are spans still open. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. When called directly from an SDK callback such as ``on_error``, shutdown is deferred to avoid blocking the worker that invoked the callback. If the callback must coordinate a blocking shutdown, have it signal an application-owned thread and return before that thread calls shutdown. Do not wait inside the callback for another thread or task that calls a lifecycle method.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span. A forked child starts with no active span; pass the parent span to continue a trace across a fork.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog = Posthog(\"\", traces={\"service_name\": \"checkout-api\"})\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is delivered on an isolated queue with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name, normally one of the `$ai_*` event names. **kwargs: Same optional arguments as `capture()`.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import capture_ai\n\nuuid = capture_ai(\n \"$ai_generation\",\n distinct_id=\"user_123\",\n properties={\"$ai_model\": \"gpt-5\"},\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip. Overriding reserved exception properties through ``properties`` is deprecated and will stop working in the next major version.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation and omit flags that cannot be evaluated locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is ``True``. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Attempt immediate delivery of queued events and ended spans, keeping the global client reusable. Call ``flush()`` before a short-lived request or serverless invocation returns when using the shared module-level client. Use ``shutdown()`` only for final process cleanup or a client that will not be reused. Flush does not stop the background workers or feature flag poller, and does not end open spans. Returning does not guarantee server receipt: pending work can remain after a timeout or span export failure, and failed events may be dropped by consumers. Calls made directly from SDK callbacks such as ``on_error`` are deferred rather than blocking the worker that invoked the callback.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Seconds to wait for event queues to drain, shared across event lanes. Defaults to 10 seconds. Pass ``None`` to wait without a time limit; this does not guarantee successful delivery. Queued spans flush concurrently, waiting up to this many seconds for an in-flight flush before starting a fresh drain budget. A lock wait timeout leaves the in-flight flush to finish. At least one span request is attempted after acquiring the lock, even with no budget left; retriable failures are retried after backoff while budget remains, with one last attempt at the deadline. The last span request is not cut short and is bounded by the client's ``timeout`` in seconds, so this is not a strict wall-clock limit for the whole call. With ``None``, a retriable span failure is left for a later flush rather than retried within this call.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "import posthog\nposthog.capture('event_name', distinct_id='user_id')\n# Before a serverless invocation returns; keep the global client open.\nposthog.flush(timeout_seconds=10)" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "Reads the `evaluation_runtime` each flag definition carries, so no extra request is made. Returns `None` when local evaluation has not loaded a definition for this key. A definition that carries no runtime reports `FeatureFlagEvaluationRuntime.ALL`, the default PostHog applies.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_evaluation_runtime\nruntime = get_feature_flag_evaluation_runtime(\"my-flag\")" - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate.", - "details": "A flag set to `FeatureFlagEvaluationRuntime.ALL` suits either runtime, so it is returned for `CLIENT` and for `SERVER`. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_keys_by_evaluation_runtime\nclient_keys = get_feature_flag_keys_by_evaluation_runtime(FeatureFlagEvaluationRuntime.CLIENT)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and stop the client's background workers. Use `shutdown()` directly in most cases. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Attempt final delivery and permanently shut down the global client. Call this for final process cleanup, not at the end of each request or serverless invocation that shares the module-level client. Use ``flush()`` before returning from those invocations instead. Shutdown closes capture lanes, stops background workers and the feature flag poller, and tears down integrations. The global client is not recreated automatically after shutdown. This normally blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Event draining has no timeout. Queued spans get a final flush with up to 30 seconds waiting for an in-flight flush, then a fresh 30-second drain budget; the last HTTP request is not cut short. Unsent queued spans and still-open spans are discarded with a warning. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. Calls made directly from SDK callbacks such as ``on_error`` are deferred to avoid deadlocking the worker. If blocking completion is required, signal an application-owned thread, return from the callback, and call ``shutdown()`` from that thread. Do not wait inside a callback for another thread or task calling a lifecycle method.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "import posthog\nposthog.traces = {\"service_name\": \"checkout-api\"}\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Tracing", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.79.0.json b/references/posthog-python-references-7.79.0.json deleted file mode 100644 index a58eca355..000000000 --- a/references/posthog-python-references-7.79.0.json +++ /dev/null @@ -1,3548 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.79.0", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "float" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "float" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "enable_full_ai_capture", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_trace_context", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "traces", - "description": "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.", - "isOptional": true, - "type": "dict" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to. Falls back to the context distinct ID; the call is dropped with a warning if neither is available.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is queued on an isolated AI lane with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are omitted from the snapshot and listed with a reason in its ``unresolved_flags``.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is True. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Attempt immediate delivery of queued events and ended spans, keeping the client reusable. For a client shared across requests or serverless invocations (including the module-level client), call ``flush()`` before a short-lived invocation returns. Use ``shutdown()`` instead only for final process cleanup or when disposing of a client that will not be reused. Flush does not stop the background workers or feature flag poller, and does not end open spans. Returning does not guarantee server receipt: pending work can remain after a timeout or span export failure, and failed events may be dropped by the consumers. Calls made directly from SDK callbacks such as ``on_error`` are deferred rather than blocking the worker that invoked the callback.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Seconds to wait for event queues to drain, shared across event lanes. Defaults to 10 seconds. Pass ``None`` to wait without a time limit; this does not guarantee successful delivery. Queued spans flush concurrently. The span exporter waits up to this many seconds for an in-flight flush, then uses a fresh drain budget once it acquires the lock. If the lock wait times out, the in-flight flush is left to finish. At least one span request is attempted after acquiring the lock, even with no budget left; retriable failures are retried after backoff while budget remains, with one last attempt at the deadline. Each span request is bounded by the client's ``timeout`` in seconds, and the last request is not cut short. This is therefore not a strict wall-clock limit for the whole call. With ``None``, a retriable span failure is left for a later flush rather than retried within this call.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name', distinct_id='user_id')\n# Before a serverless invocation returns; keep the shared client open.\nposthog.flush(timeout_seconds=10)" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nruntime = posthog.get_feature_flag_evaluation_runtime(\"my-flag\")\nif runtime is FeatureFlagEvaluationRuntime.SERVER:\n ..." - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate. A flag set to ``FeatureFlagEvaluationRuntime.ALL`` suits either runtime, so it is returned for ``CLIENT`` and for ``SERVER``, and asking for ``ALL`` returns every loaded flag. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "The runtime to match, as a ``FeatureFlagEvaluationRuntime`` or its string value.", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nclient_keys = posthog.get_feature_flag_keys_by_evaluation_runtime(\n FeatureFlagEvaluationRuntime.CLIENT\n)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user, preserving valid serialized JSON.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Optional[str]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team'). Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and end the consumer threads. Do not use directly, call `shutdown()` instead. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Attempt final delivery and permanently shut down the client. Call this for final process cleanup or when disposing of a client that will not be reused. It closes capture lanes, stops background workers and the feature flag poller, and tears down integrations. Do not call it at the end of each request or serverless invocation when the client is shared; call ``flush()`` before returning instead. A shut-down client cannot be reused; create a new client if needed. Normally this method blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Event draining has no timeout. Queued spans get one final flush with up to 30 seconds waiting for an in-flight flush, then a fresh 30-second drain budget; the last HTTP request is not cut short. Any spans it cannot send are discarded with a warning, as are spans still open. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. When called directly from an SDK callback such as ``on_error``, shutdown is deferred to avoid blocking the worker that invoked the callback. If the callback must coordinate a blocking shutdown, have it signal an application-owned thread and return before that thread calls shutdown. Do not wait inside the callback for another thread or task that calls a lifecycle method.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span. A forked child starts with no active span; pass the parent span to continue a trace across a fork.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog = Posthog(\"\", traces={\"service_name\": \"checkout-api\"})\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is delivered on an isolated queue with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name, normally one of the `$ai_*` event names. **kwargs: Same optional arguments as `capture()`.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import capture_ai\n\nuuid = capture_ai(\n \"$ai_generation\",\n distinct_id=\"user_123\",\n properties={\"$ai_model\": \"gpt-5\"},\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip. Overriding reserved exception properties through ``properties`` is deprecated and will stop working in the next major version.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation and omit flags that cannot be evaluated locally. The snapshot's ``unresolved_flags`` lists them with a reason.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is ``True``. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Attempt immediate delivery of queued events and ended spans, keeping the global client reusable. Call ``flush()`` before a short-lived request or serverless invocation returns when using the shared module-level client. Use ``shutdown()`` only for final process cleanup or a client that will not be reused. Flush does not stop the background workers or feature flag poller, and does not end open spans. Returning does not guarantee server receipt: pending work can remain after a timeout or span export failure, and failed events may be dropped by consumers. Calls made directly from SDK callbacks such as ``on_error`` are deferred rather than blocking the worker that invoked the callback.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Seconds to wait for event queues to drain, shared across event lanes. Defaults to 10 seconds. Pass ``None`` to wait without a time limit; this does not guarantee successful delivery. Queued spans flush concurrently, waiting up to this many seconds for an in-flight flush before starting a fresh drain budget. A lock wait timeout leaves the in-flight flush to finish. At least one span request is attempted after acquiring the lock, even with no budget left; retriable failures are retried after backoff while budget remains, with one last attempt at the deadline. The last span request is not cut short and is bounded by the client's ``timeout`` in seconds, so this is not a strict wall-clock limit for the whole call. With ``None``, a retriable span failure is left for a later flush rather than retried within this call.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "import posthog\nposthog.capture('event_name', distinct_id='user_id')\n# Before a serverless invocation returns; keep the global client open.\nposthog.flush(timeout_seconds=10)" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "Reads the `evaluation_runtime` each flag definition carries, so no extra request is made. Returns `None` when local evaluation has not loaded a definition for this key. A definition that carries no runtime reports `FeatureFlagEvaluationRuntime.ALL`, the default PostHog applies.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_evaluation_runtime\nruntime = get_feature_flag_evaluation_runtime(\"my-flag\")" - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate.", - "details": "A flag set to `FeatureFlagEvaluationRuntime.ALL` suits either runtime, so it is returned for `CLIENT` and for `SERVER`. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_keys_by_evaluation_runtime\nclient_keys = get_feature_flag_keys_by_evaluation_runtime(FeatureFlagEvaluationRuntime.CLIENT)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and stop the client's background workers. Use `shutdown()` directly in most cases. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Attempt final delivery and permanently shut down the global client. Call this for final process cleanup, not at the end of each request or serverless invocation that shares the module-level client. Use ``flush()`` before returning from those invocations instead. Shutdown closes capture lanes, stops background workers and the feature flag poller, and tears down integrations. The global client is not recreated automatically after shutdown. This normally blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Event draining has no timeout. Queued spans get a final flush with up to 30 seconds waiting for an in-flight flush, then a fresh 30-second drain budget; the last HTTP request is not cut short. Unsent queued spans and still-open spans are discarded with a warning. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. Calls made directly from SDK callbacks such as ``on_error`` are deferred to avoid deadlocking the worker. If blocking completion is required, signal an application-owned thread, return from the callback, and call ``shutdown()`` from that thread. Do not wait inside a callback for another thread or task calling a lifecycle method.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "import posthog\nposthog.traces = {\"service_name\": \"checkout-api\"}\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Tracing", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.80.0.json b/references/posthog-python-references-7.80.0.json deleted file mode 100644 index cecc19693..000000000 --- a/references/posthog-python-references-7.80.0.json +++ /dev/null @@ -1,3548 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.80.0", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "float" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "float" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "enable_full_ai_capture", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_trace_context", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "traces", - "description": "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.", - "isOptional": true, - "type": "dict" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to. Falls back to the context distinct ID; the call is dropped with a warning if neither is available.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is queued on an isolated AI lane with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are omitted from the snapshot and listed with a reason in its ``unresolved_flags``.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is True. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Attempt immediate delivery of queued events, ended spans and autocaptured metrics, keeping the client reusable. For a client shared across requests or serverless invocations (including the module-level client), call ``flush()`` before a short-lived invocation returns. Use ``shutdown()`` instead only for final process cleanup or when disposing of a client that will not be reused. Flush does not stop the background workers or feature flag poller, and does not end open spans. Returning does not guarantee server receipt: pending work can remain after a timeout or span export failure, and failed events may be dropped by the consumers. Calls made directly from SDK callbacks such as ``on_error`` are deferred rather than blocking the worker that invoked the callback.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Seconds to wait for event queues to drain, shared across event lanes. Defaults to 10 seconds. Pass ``None`` to wait without a time limit; this does not guarantee successful delivery. Queued spans flush concurrently. The span exporter waits up to this many seconds for an in-flight flush, then uses a fresh drain budget once it acquires the lock. If the lock wait times out, the in-flight flush is left to finish. At least one span request is attempted after acquiring the lock, even with no budget left; retriable failures are retried after backoff while budget remains, with one last attempt at the deadline. Each span request is bounded by the client's ``timeout`` in seconds, and the last request is not cut short. This is therefore not a strict wall-clock limit for the whole call. With ``None``, a retriable span failure is left for a later flush rather than retried within this call.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name', distinct_id='user_id')\n# Before a serverless invocation returns; keep the shared client open.\nposthog.flush(timeout_seconds=10)" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nruntime = posthog.get_feature_flag_evaluation_runtime(\"my-flag\")\nif runtime is FeatureFlagEvaluationRuntime.SERVER:\n ..." - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate. A flag set to ``FeatureFlagEvaluationRuntime.ALL`` suits either runtime, so it is returned for ``CLIENT`` and for ``SERVER``, and asking for ``ALL`` returns every loaded flag. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "The runtime to match, as a ``FeatureFlagEvaluationRuntime`` or its string value.", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nclient_keys = posthog.get_feature_flag_keys_by_evaluation_runtime(\n FeatureFlagEvaluationRuntime.CLIENT\n)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user, preserving valid serialized JSON.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Optional[str]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team'). Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and end the consumer threads. Do not use directly, call `shutdown()` instead. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Attempt final delivery and permanently shut down the client. Call this for final process cleanup or when disposing of a client that will not be reused. It closes capture lanes, stops background workers and the feature flag poller, and tears down integrations. Do not call it at the end of each request or serverless invocation when the client is shared; call ``flush()`` before returning instead. A shut-down client cannot be reused; create a new client if needed. Normally this method blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Event draining has no timeout. Queued spans get one final flush with up to 30 seconds waiting for an in-flight flush, then a fresh 30-second drain budget; the last HTTP request is not cut short. Any spans it cannot send are discarded with a warning, as are spans still open. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. When called directly from an SDK callback such as ``on_error``, shutdown is deferred to avoid blocking the worker that invoked the callback. If the callback must coordinate a blocking shutdown, have it signal an application-owned thread and return before that thread calls shutdown. Do not wait inside the callback for another thread or task that calls a lifecycle method.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span. A forked child starts with no active span; pass the parent span to continue a trace across a fork.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog = Posthog(\"\", traces={\"service_name\": \"checkout-api\"})\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is delivered on an isolated queue with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name, normally one of the `$ai_*` event names. **kwargs: Same optional arguments as `capture()`.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import capture_ai\n\nuuid = capture_ai(\n \"$ai_generation\",\n distinct_id=\"user_123\",\n properties={\"$ai_model\": \"gpt-5\"},\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip. Overriding reserved exception properties through ``properties`` is deprecated and will stop working in the next major version.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation and omit flags that cannot be evaluated locally. The snapshot's ``unresolved_flags`` lists them with a reason.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is ``True``. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Attempt immediate delivery of queued events and ended spans, keeping the global client reusable. Call ``flush()`` before a short-lived request or serverless invocation returns when using the shared module-level client. Use ``shutdown()`` only for final process cleanup or a client that will not be reused. Flush does not stop the background workers or feature flag poller, and does not end open spans. Returning does not guarantee server receipt: pending work can remain after a timeout or span export failure, and failed events may be dropped by consumers. Calls made directly from SDK callbacks such as ``on_error`` are deferred rather than blocking the worker that invoked the callback.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Seconds to wait for event queues to drain, shared across event lanes. Defaults to 10 seconds. Pass ``None`` to wait without a time limit; this does not guarantee successful delivery. Queued spans flush concurrently, waiting up to this many seconds for an in-flight flush before starting a fresh drain budget. A lock wait timeout leaves the in-flight flush to finish. At least one span request is attempted after acquiring the lock, even with no budget left; retriable failures are retried after backoff while budget remains, with one last attempt at the deadline. The last span request is not cut short and is bounded by the client's ``timeout`` in seconds, so this is not a strict wall-clock limit for the whole call. With ``None``, a retriable span failure is left for a later flush rather than retried within this call.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "import posthog\nposthog.capture('event_name', distinct_id='user_id')\n# Before a serverless invocation returns; keep the global client open.\nposthog.flush(timeout_seconds=10)" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "Reads the `evaluation_runtime` each flag definition carries, so no extra request is made. Returns `None` when local evaluation has not loaded a definition for this key. A definition that carries no runtime reports `FeatureFlagEvaluationRuntime.ALL`, the default PostHog applies.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_evaluation_runtime\nruntime = get_feature_flag_evaluation_runtime(\"my-flag\")" - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate.", - "details": "A flag set to `FeatureFlagEvaluationRuntime.ALL` suits either runtime, so it is returned for `CLIENT` and for `SERVER`. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_keys_by_evaluation_runtime\nclient_keys = get_feature_flag_keys_by_evaluation_runtime(FeatureFlagEvaluationRuntime.CLIENT)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and stop the client's background workers. Use `shutdown()` directly in most cases. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Attempt final delivery and permanently shut down the global client. Call this for final process cleanup, not at the end of each request or serverless invocation that shares the module-level client. Use ``flush()`` before returning from those invocations instead. Shutdown closes capture lanes, stops background workers and the feature flag poller, and tears down integrations. The global client is not recreated automatically after shutdown. This normally blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Event draining has no timeout. Queued spans get a final flush with up to 30 seconds waiting for an in-flight flush, then a fresh 30-second drain budget; the last HTTP request is not cut short. Unsent queued spans and still-open spans are discarded with a warning. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. Calls made directly from SDK callbacks such as ``on_error`` are deferred to avoid deadlocking the worker. If blocking completion is required, signal an application-owned thread, return from the callback, and call ``shutdown()`` from that thread. Do not wait inside a callback for another thread or task calling a lifecycle method.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "import posthog\nposthog.traces = {\"service_name\": \"checkout-api\"}\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Tracing", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.80.1.json b/references/posthog-python-references-7.80.1.json deleted file mode 100644 index 841a5b2d4..000000000 --- a/references/posthog-python-references-7.80.1.json +++ /dev/null @@ -1,3548 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.80.1", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "float" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "float" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "enable_full_ai_capture", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_trace_context", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "traces", - "description": "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.", - "isOptional": true, - "type": "dict" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to. Falls back to the context distinct ID; the call is dropped with a warning if neither is available.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is queued on an isolated AI lane with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are omitted from the snapshot and listed with a reason in its ``unresolved_flags``.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is True. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Attempt immediate delivery of queued events, ended spans and autocaptured metrics, keeping the client reusable. For a client shared across requests or serverless invocations (including the module-level client), call ``flush()`` before a short-lived invocation returns. Use ``shutdown()`` instead only for final process cleanup or when disposing of a client that will not be reused. Flush does not stop the background workers or feature flag poller, and does not end open spans. Returning does not guarantee server receipt: pending work can remain after a timeout or span export failure, and failed events may be dropped by the consumers. Calls made directly from SDK callbacks such as ``on_error`` are deferred rather than blocking the worker that invoked the callback.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Seconds to wait for event queues to drain, shared across event lanes. Defaults to 10 seconds. Pass ``None`` to wait without a time limit; this does not guarantee successful delivery. Queued spans flush concurrently. The span exporter waits up to this many seconds for an in-flight flush, then uses a fresh drain budget once it acquires the lock. If the lock wait times out, the in-flight flush is left to finish. At least one span request is attempted after acquiring the lock, even with no budget left; retriable failures are retried after backoff while budget remains, with one last attempt at the deadline. Each span request is bounded by the client's ``timeout`` in seconds, and the last request is not cut short. This is therefore not a strict wall-clock limit for the whole call. With ``None``, a retriable span failure is left for a later flush rather than retried within this call.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name', distinct_id='user_id')\n# Before a serverless invocation returns; keep the shared client open.\nposthog.flush(timeout_seconds=10)" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nruntime = posthog.get_feature_flag_evaluation_runtime(\"my-flag\")\nif runtime is FeatureFlagEvaluationRuntime.SERVER:\n ..." - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate. A flag set to ``FeatureFlagEvaluationRuntime.ALL`` suits either runtime, so it is returned for ``CLIENT`` and for ``SERVER``, and asking for ``ALL`` returns every loaded flag. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "The runtime to match, as a ``FeatureFlagEvaluationRuntime`` or its string value.", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nclient_keys = posthog.get_feature_flag_keys_by_evaluation_runtime(\n FeatureFlagEvaluationRuntime.CLIENT\n)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user, preserving valid serialized JSON.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Optional[str]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team'). Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and end the consumer threads. Do not use directly, call `shutdown()` instead. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Attempt final delivery and permanently shut down the client. Call this for final process cleanup or when disposing of a client that will not be reused. It closes capture lanes, stops background workers and the feature flag poller, and tears down integrations. Do not call it at the end of each request or serverless invocation when the client is shared; call ``flush()`` before returning instead. A shut-down client cannot be reused; create a new client if needed. Normally this method blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Event draining has no timeout. Queued spans get one final flush with up to 30 seconds waiting for an in-flight flush, then a fresh 30-second drain budget; the last HTTP request is not cut short. Any spans it cannot send are discarded with a warning, as are spans still open. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. When called directly from an SDK callback such as ``on_error``, shutdown is deferred to avoid blocking the worker that invoked the callback. If the callback must coordinate a blocking shutdown, have it signal an application-owned thread and return before that thread calls shutdown. Do not wait inside the callback for another thread or task that calls a lifecycle method.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span. A forked child starts with no active span; pass the parent span to continue a trace across a fork.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog = Posthog(\"\", traces={\"service_name\": \"checkout-api\"})\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is delivered on an isolated queue with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name, normally one of the `$ai_*` event names. **kwargs: Same optional arguments as `capture()`.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import capture_ai\n\nuuid = capture_ai(\n \"$ai_generation\",\n distinct_id=\"user_123\",\n properties={\"$ai_model\": \"gpt-5\"},\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip. Overriding reserved exception properties through ``properties`` is deprecated and will stop working in the next major version.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation and omit flags that cannot be evaluated locally. The snapshot's ``unresolved_flags`` lists them with a reason.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is ``True``. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Attempt immediate delivery of queued events and ended spans, keeping the global client reusable. Call ``flush()`` before a short-lived request or serverless invocation returns when using the shared module-level client. Use ``shutdown()`` only for final process cleanup or a client that will not be reused. Flush does not stop the background workers or feature flag poller, and does not end open spans. Returning does not guarantee server receipt: pending work can remain after a timeout or span export failure, and failed events may be dropped by consumers. Calls made directly from SDK callbacks such as ``on_error`` are deferred rather than blocking the worker that invoked the callback.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Seconds to wait for event queues to drain, shared across event lanes. Defaults to 10 seconds. Pass ``None`` to wait without a time limit; this does not guarantee successful delivery. Queued spans flush concurrently, waiting up to this many seconds for an in-flight flush before starting a fresh drain budget. A lock wait timeout leaves the in-flight flush to finish. At least one span request is attempted after acquiring the lock, even with no budget left; retriable failures are retried after backoff while budget remains, with one last attempt at the deadline. The last span request is not cut short and is bounded by the client's ``timeout`` in seconds, so this is not a strict wall-clock limit for the whole call. With ``None``, a retriable span failure is left for a later flush rather than retried within this call.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "import posthog\nposthog.capture('event_name', distinct_id='user_id')\n# Before a serverless invocation returns; keep the global client open.\nposthog.flush(timeout_seconds=10)" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "Reads the `evaluation_runtime` each flag definition carries, so no extra request is made. Returns `None` when local evaluation has not loaded a definition for this key. A definition that carries no runtime reports `FeatureFlagEvaluationRuntime.ALL`, the default PostHog applies.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_evaluation_runtime\nruntime = get_feature_flag_evaluation_runtime(\"my-flag\")" - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate.", - "details": "A flag set to `FeatureFlagEvaluationRuntime.ALL` suits either runtime, so it is returned for `CLIENT` and for `SERVER`. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_keys_by_evaluation_runtime\nclient_keys = get_feature_flag_keys_by_evaluation_runtime(FeatureFlagEvaluationRuntime.CLIENT)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and stop the client's background workers. Use `shutdown()` directly in most cases. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Attempt final delivery and permanently shut down the global client. Call this for final process cleanup, not at the end of each request or serverless invocation that shares the module-level client. Use ``flush()`` before returning from those invocations instead. Shutdown closes capture lanes, stops background workers and the feature flag poller, and tears down integrations. The global client is not recreated automatically after shutdown. This normally blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Event draining has no timeout. Queued spans get a final flush with up to 30 seconds waiting for an in-flight flush, then a fresh 30-second drain budget; the last HTTP request is not cut short. Unsent queued spans and still-open spans are discarded with a warning. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. Calls made directly from SDK callbacks such as ``on_error`` are deferred to avoid deadlocking the worker. If blocking completion is required, signal an application-owned thread, return from the callback, and call ``shutdown()`` from that thread. Do not wait inside a callback for another thread or task calling a lifecycle method.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "import posthog\nposthog.traces = {\"service_name\": \"checkout-api\"}\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Tracing", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.80.2.json b/references/posthog-python-references-7.80.2.json deleted file mode 100644 index d8cd45066..000000000 --- a/references/posthog-python-references-7.80.2.json +++ /dev/null @@ -1,3548 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.80.2", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "float" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "float" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "enable_full_ai_capture", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_trace_context", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "traces", - "description": "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.", - "isOptional": true, - "type": "dict" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to. Falls back to the context distinct ID; the call is dropped with a warning if neither is available.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is queued on an isolated AI lane with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are omitted from the snapshot and listed with a reason in its ``unresolved_flags``.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is True. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Attempt immediate delivery of queued events, ended spans and autocaptured metrics, keeping the client reusable. For a client shared across requests or serverless invocations (including the module-level client), call ``flush()`` before a short-lived invocation returns. Use ``shutdown()`` instead only for final process cleanup or when disposing of a client that will not be reused. Flush does not stop the background workers or feature flag poller, and does not end open spans. Returning does not guarantee server receipt: pending work can remain after a timeout or span export failure, and failed events may be dropped by the consumers. Calls made directly from SDK callbacks such as ``on_error`` are deferred rather than blocking the worker that invoked the callback.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Seconds to wait for event queues to drain, shared across event lanes. Defaults to 10 seconds. Pass ``None`` to wait without a time limit; this does not guarantee successful delivery. Queued spans flush concurrently. The span exporter waits up to this many seconds for an in-flight flush, then uses a fresh drain budget once it acquires the lock. If the lock wait times out, the in-flight flush is left to finish. At least one span request is attempted after acquiring the lock, even with no budget left; retriable failures are retried after backoff while budget remains, with one last attempt at the deadline. Each span request is bounded by the client's ``timeout`` in seconds, and the last request is not cut short. This is therefore not a strict wall-clock limit for the whole call. With ``None``, a retriable span failure is left for a later flush rather than retried within this call.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name', distinct_id='user_id')\n# Before a serverless invocation returns; keep the shared client open.\nposthog.flush(timeout_seconds=10)" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nruntime = posthog.get_feature_flag_evaluation_runtime(\"my-flag\")\nif runtime is FeatureFlagEvaluationRuntime.SERVER:\n ..." - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate. A flag set to ``FeatureFlagEvaluationRuntime.ALL`` suits either runtime, so it is returned for ``CLIENT`` and for ``SERVER``, and asking for ``ALL`` returns every loaded flag. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "The runtime to match, as a ``FeatureFlagEvaluationRuntime`` or its string value.", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nclient_keys = posthog.get_feature_flag_keys_by_evaluation_runtime(\n FeatureFlagEvaluationRuntime.CLIENT\n)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user, preserving valid serialized JSON.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Optional[str]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team'). Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and end the consumer threads. Do not use directly, call `shutdown()` instead. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Attempt final delivery and permanently shut down the client. Call this for final process cleanup or when disposing of a client that will not be reused. It closes capture lanes, stops background workers and the feature flag poller, and tears down integrations. Do not call it at the end of each request or serverless invocation when the client is shared; call ``flush()`` before returning instead. A shut-down client cannot be reused; create a new client if needed. Normally this method blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Event draining has no timeout. Queued spans get one final flush with up to 30 seconds waiting for an in-flight flush, then a fresh 30-second drain budget; the last HTTP request is not cut short. Any spans it cannot send are discarded with a warning, as are spans still open. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. When called directly from an SDK callback such as ``on_error``, shutdown is deferred to avoid blocking the worker that invoked the callback. If the callback must coordinate a blocking shutdown, have it signal an application-owned thread and return before that thread calls shutdown. Do not wait inside the callback for another thread or task that calls a lifecycle method.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span. A forked child starts with no active span; pass the parent span to continue a trace across a fork.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog = Posthog(\"\", traces={\"service_name\": \"checkout-api\"})\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is delivered on an isolated queue with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name, normally one of the `$ai_*` event names. **kwargs: Same optional arguments as `capture()`.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import capture_ai\n\nuuid = capture_ai(\n \"$ai_generation\",\n distinct_id=\"user_123\",\n properties={\"$ai_model\": \"gpt-5\"},\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip. Overriding reserved exception properties through ``properties`` is deprecated and will stop working in the next major version.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation and omit flags that cannot be evaluated locally. The snapshot's ``unresolved_flags`` lists them with a reason.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is ``True``. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Attempt immediate delivery of queued events and ended spans, keeping the global client reusable. Call ``flush()`` before a short-lived request or serverless invocation returns when using the shared module-level client. Use ``shutdown()`` only for final process cleanup or a client that will not be reused. Flush does not stop the background workers or feature flag poller, and does not end open spans. Returning does not guarantee server receipt: pending work can remain after a timeout or span export failure, and failed events may be dropped by consumers. Calls made directly from SDK callbacks such as ``on_error`` are deferred rather than blocking the worker that invoked the callback.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Seconds to wait for event queues to drain, shared across event lanes. Defaults to 10 seconds. Pass ``None`` to wait without a time limit; this does not guarantee successful delivery. Queued spans flush concurrently, waiting up to this many seconds for an in-flight flush before starting a fresh drain budget. A lock wait timeout leaves the in-flight flush to finish. At least one span request is attempted after acquiring the lock, even with no budget left; retriable failures are retried after backoff while budget remains, with one last attempt at the deadline. The last span request is not cut short and is bounded by the client's ``timeout`` in seconds, so this is not a strict wall-clock limit for the whole call. With ``None``, a retriable span failure is left for a later flush rather than retried within this call.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "import posthog\nposthog.capture('event_name', distinct_id='user_id')\n# Before a serverless invocation returns; keep the global client open.\nposthog.flush(timeout_seconds=10)" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "Reads the `evaluation_runtime` each flag definition carries, so no extra request is made. Returns `None` when local evaluation has not loaded a definition for this key. A definition that carries no runtime reports `FeatureFlagEvaluationRuntime.ALL`, the default PostHog applies.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_evaluation_runtime\nruntime = get_feature_flag_evaluation_runtime(\"my-flag\")" - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate.", - "details": "A flag set to `FeatureFlagEvaluationRuntime.ALL` suits either runtime, so it is returned for `CLIENT` and for `SERVER`. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_keys_by_evaluation_runtime\nclient_keys = get_feature_flag_keys_by_evaluation_runtime(FeatureFlagEvaluationRuntime.CLIENT)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and stop the client's background workers. Use `shutdown()` directly in most cases. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Attempt final delivery and permanently shut down the global client. Call this for final process cleanup, not at the end of each request or serverless invocation that shares the module-level client. Use ``flush()`` before returning from those invocations instead. Shutdown closes capture lanes, stops background workers and the feature flag poller, and tears down integrations. The global client is not recreated automatically after shutdown. This normally blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Event draining has no timeout. Queued spans get a final flush with up to 30 seconds waiting for an in-flight flush, then a fresh 30-second drain budget; the last HTTP request is not cut short. Unsent queued spans and still-open spans are discarded with a warning. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. Calls made directly from SDK callbacks such as ``on_error`` are deferred to avoid deadlocking the worker. If blocking completion is required, signal an application-owned thread, return from the callback, and call ``shutdown()`` from that thread. Do not wait inside a callback for another thread or task calling a lifecycle method.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "import posthog\nposthog.traces = {\"service_name\": \"checkout-api\"}\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Tracing", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.80.3.json b/references/posthog-python-references-7.80.3.json deleted file mode 100644 index 8ee9a06c2..000000000 --- a/references/posthog-python-references-7.80.3.json +++ /dev/null @@ -1,3548 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.80.3", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "float" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "float" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "enable_full_ai_capture", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_trace_context", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "traces", - "description": "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.", - "isOptional": true, - "type": "dict" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to. Falls back to the context distinct ID; the call is dropped with a warning if neither is available.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is queued on an isolated AI lane with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are omitted from the snapshot and listed with a reason in its ``unresolved_flags``.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is True. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Attempt immediate delivery of queued events, ended spans and autocaptured metrics, keeping the client reusable. For a client shared across requests or serverless invocations (including the module-level client), call ``flush()`` before a short-lived invocation returns. Use ``shutdown()`` instead only for final process cleanup or when disposing of a client that will not be reused. Flush does not stop the background workers or feature flag poller, and does not end open spans. Returning does not guarantee server receipt: pending work can remain after a timeout or span export failure, and failed events may be dropped by the consumers. Calls made directly from SDK callbacks such as ``on_error`` are deferred rather than blocking the worker that invoked the callback.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Seconds to wait for event queues to drain, shared across event lanes. Defaults to 10 seconds. Pass ``None`` to wait without a time limit; this does not guarantee successful delivery. Queued spans flush concurrently. The span exporter waits up to this many seconds for an in-flight flush, then uses a fresh drain budget once it acquires the lock. If the lock wait times out, the in-flight flush is left to finish. At least one span request is attempted after acquiring the lock, even with no budget left; retriable failures are retried after backoff while budget remains, with one last attempt at the deadline. Each span request is bounded by the client's ``timeout`` in seconds, and the last request is not cut short. This is therefore not a strict wall-clock limit for the whole call. With ``None``, a retriable span failure is left for a later flush rather than retried within this call.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name', distinct_id='user_id')\n# Before a serverless invocation returns; keep the shared client open.\nposthog.flush(timeout_seconds=10)" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nruntime = posthog.get_feature_flag_evaluation_runtime(\"my-flag\")\nif runtime is FeatureFlagEvaluationRuntime.SERVER:\n ..." - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate. A flag set to ``FeatureFlagEvaluationRuntime.ALL`` suits either runtime, so it is returned for ``CLIENT`` and for ``SERVER``, and asking for ``ALL`` returns every loaded flag. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "The runtime to match, as a ``FeatureFlagEvaluationRuntime`` or its string value.", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nclient_keys = posthog.get_feature_flag_keys_by_evaluation_runtime(\n FeatureFlagEvaluationRuntime.CLIENT\n)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user, preserving valid serialized JSON.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Optional[str]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team'). Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and end the consumer threads. Do not use directly, call `shutdown()` instead. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Attempt final delivery and permanently shut down the client. Call this for final process cleanup or when disposing of a client that will not be reused. It closes capture lanes, stops background workers and the feature flag poller, and tears down integrations. Do not call it at the end of each request or serverless invocation when the client is shared; call ``flush()`` before returning instead. A shut-down client cannot be reused; create a new client if needed. Normally this method blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Event draining has no timeout. Queued spans get one final flush with up to 30 seconds waiting for an in-flight flush, then a fresh 30-second drain budget; the last HTTP request is not cut short. Any spans it cannot send are discarded with a warning, as are spans still open. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. When called directly from an SDK callback such as ``on_error``, shutdown is deferred to avoid blocking the worker that invoked the callback. If the callback must coordinate a blocking shutdown, have it signal an application-owned thread and return before that thread calls shutdown. Do not wait inside the callback for another thread or task that calls a lifecycle method.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span. A forked child starts with no active span; pass the parent span to continue a trace across a fork.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog = Posthog(\"\", traces={\"service_name\": \"checkout-api\"})\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is delivered on an isolated queue with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name, normally one of the `$ai_*` event names. **kwargs: Same optional arguments as `capture()`.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import capture_ai\n\nuuid = capture_ai(\n \"$ai_generation\",\n distinct_id=\"user_123\",\n properties={\"$ai_model\": \"gpt-5\"},\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip. Overriding reserved exception properties through ``properties`` is deprecated and will stop working in the next major version.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation and omit flags that cannot be evaluated locally. The snapshot's ``unresolved_flags`` lists them with a reason.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is ``True``. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Attempt immediate delivery of queued events and ended spans, keeping the global client reusable. Call ``flush()`` before a short-lived request or serverless invocation returns when using the shared module-level client. Use ``shutdown()`` only for final process cleanup or a client that will not be reused. Flush does not stop the background workers or feature flag poller, and does not end open spans. Returning does not guarantee server receipt: pending work can remain after a timeout or span export failure, and failed events may be dropped by consumers. Calls made directly from SDK callbacks such as ``on_error`` are deferred rather than blocking the worker that invoked the callback.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Seconds to wait for event queues to drain, shared across event lanes. Defaults to 10 seconds. Pass ``None`` to wait without a time limit; this does not guarantee successful delivery. Queued spans flush concurrently, waiting up to this many seconds for an in-flight flush before starting a fresh drain budget. A lock wait timeout leaves the in-flight flush to finish. At least one span request is attempted after acquiring the lock, even with no budget left; retriable failures are retried after backoff while budget remains, with one last attempt at the deadline. The last span request is not cut short and is bounded by the client's ``timeout`` in seconds, so this is not a strict wall-clock limit for the whole call. With ``None``, a retriable span failure is left for a later flush rather than retried within this call.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "import posthog\nposthog.capture('event_name', distinct_id='user_id')\n# Before a serverless invocation returns; keep the global client open.\nposthog.flush(timeout_seconds=10)" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "Reads the `evaluation_runtime` each flag definition carries, so no extra request is made. Returns `None` when local evaluation has not loaded a definition for this key. A definition that carries no runtime reports `FeatureFlagEvaluationRuntime.ALL`, the default PostHog applies.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_evaluation_runtime\nruntime = get_feature_flag_evaluation_runtime(\"my-flag\")" - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate.", - "details": "A flag set to `FeatureFlagEvaluationRuntime.ALL` suits either runtime, so it is returned for `CLIENT` and for `SERVER`. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_keys_by_evaluation_runtime\nclient_keys = get_feature_flag_keys_by_evaluation_runtime(FeatureFlagEvaluationRuntime.CLIENT)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and stop the client's background workers. Use `shutdown()` directly in most cases. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Attempt final delivery and permanently shut down the global client. Call this for final process cleanup, not at the end of each request or serverless invocation that shares the module-level client. Use ``flush()`` before returning from those invocations instead. Shutdown closes capture lanes, stops background workers and the feature flag poller, and tears down integrations. The global client is not recreated automatically after shutdown. This normally blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Event draining has no timeout. Queued spans get a final flush with up to 30 seconds waiting for an in-flight flush, then a fresh 30-second drain budget; the last HTTP request is not cut short. Unsent queued spans and still-open spans are discarded with a warning. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. Calls made directly from SDK callbacks such as ``on_error`` are deferred to avoid deadlocking the worker. If blocking completion is required, signal an application-owned thread, return from the callback, and call ``shutdown()`` from that thread. Do not wait inside a callback for another thread or task calling a lifecycle method.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "import posthog\nposthog.traces = {\"service_name\": \"checkout-api\"}\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Tracing", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.81.0.json b/references/posthog-python-references-7.81.0.json deleted file mode 100644 index 7c2dd117a..000000000 --- a/references/posthog-python-references-7.81.0.json +++ /dev/null @@ -1,3566 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.81.0", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "float" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "float" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "enable_full_ai_capture", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_trace_context", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "traces", - "description": "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.", - "isOptional": true, - "type": "dict" - }, - { - "name": "app_host", - "description": "Your PostHog app host, such as ``https://posthog.example.com``. ``emails`` sends there. Needed only when ``host`` is not PostHog Cloud, for example a reverse proxy, which must not receive the secret key.", - "isOptional": true, - "type": "str" - }, - { - "name": "email_request_timeout_seconds", - "description": "Timeout in seconds for each email send request. Defaults to 15.", - "isOptional": false, - "type": "float" - }, - { - "name": "email_request_max_retries", - "description": "Number of retries for an email send after a network error, a rate limit, or an unavailable service. Defaults to 2. Set to 0 when a job runner already retries the send.", - "isOptional": false, - "type": "int" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to. Falls back to the context distinct ID; the call is dropped with a warning if neither is available.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is queued on an isolated AI lane with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are omitted from the snapshot and listed with a reason in its ``unresolved_flags``.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is True. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Attempt immediate delivery of queued events, ended spans and autocaptured metrics, keeping the client reusable. For a client shared across requests or serverless invocations (including the module-level client), call ``flush()`` before a short-lived invocation returns. Use ``shutdown()`` instead only for final process cleanup or when disposing of a client that will not be reused. Flush does not stop the background workers or feature flag poller, and does not end open spans. Returning does not guarantee server receipt: pending work can remain after a timeout or span export failure, and failed events may be dropped by the consumers. Calls made directly from SDK callbacks such as ``on_error`` are deferred rather than blocking the worker that invoked the callback.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Seconds to wait for event queues to drain, shared across event lanes. Defaults to 10 seconds. Pass ``None`` to wait without a time limit; this does not guarantee successful delivery. Queued spans flush concurrently. The span exporter waits up to this many seconds for an in-flight flush, then uses a fresh drain budget once it acquires the lock. If the lock wait times out, the in-flight flush is left to finish. At least one span request is attempted after acquiring the lock, even with no budget left; retriable failures are retried after backoff while budget remains, with one last attempt at the deadline. Each span request is bounded by the client's ``timeout`` in seconds, and the last request is not cut short. This is therefore not a strict wall-clock limit for the whole call. With ``None``, a retriable span failure is left for a later flush rather than retried within this call.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name', distinct_id='user_id')\n# Before a serverless invocation returns; keep the shared client open.\nposthog.flush(timeout_seconds=10)" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nruntime = posthog.get_feature_flag_evaluation_runtime(\"my-flag\")\nif runtime is FeatureFlagEvaluationRuntime.SERVER:\n ..." - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate. A flag set to ``FeatureFlagEvaluationRuntime.ALL`` suits either runtime, so it is returned for ``CLIENT`` and for ``SERVER``, and asking for ``ALL`` returns every loaded flag. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "The runtime to match, as a ``FeatureFlagEvaluationRuntime`` or its string value.", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nclient_keys = posthog.get_feature_flag_keys_by_evaluation_runtime(\n FeatureFlagEvaluationRuntime.CLIENT\n)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user, preserving valid serialized JSON.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Optional[str]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team'). Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and end the consumer threads. Do not use directly, call `shutdown()` instead. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Attempt final delivery and permanently shut down the client. Call this for final process cleanup or when disposing of a client that will not be reused. It closes capture lanes, stops background workers and the feature flag poller, and tears down integrations. Do not call it at the end of each request or serverless invocation when the client is shared; call ``flush()`` before returning instead. A shut-down client cannot be reused; create a new client if needed. Normally this method blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Event draining has no timeout. Queued spans get one final flush with up to 30 seconds waiting for an in-flight flush, then a fresh 30-second drain budget; the last HTTP request is not cut short. Any spans it cannot send are discarded with a warning, as are spans still open. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. When called directly from an SDK callback such as ``on_error``, shutdown is deferred to avoid blocking the worker that invoked the callback. If the callback must coordinate a blocking shutdown, have it signal an application-owned thread and return before that thread calls shutdown. Do not wait inside the callback for another thread or task that calls a lifecycle method.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span. A forked child starts with no active span; pass the parent span to continue a trace across a fork.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog = Posthog(\"\", traces={\"service_name\": \"checkout-api\"})\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is delivered on an isolated queue with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name, normally one of the `$ai_*` event names. **kwargs: Same optional arguments as `capture()`.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import capture_ai\n\nuuid = capture_ai(\n \"$ai_generation\",\n distinct_id=\"user_123\",\n properties={\"$ai_model\": \"gpt-5\"},\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip. Overriding reserved exception properties through ``properties`` is deprecated and will stop working in the next major version.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation and omit flags that cannot be evaluated locally. The snapshot's ``unresolved_flags`` lists them with a reason.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is ``True``. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Attempt immediate delivery of queued events and ended spans, keeping the global client reusable. Call ``flush()`` before a short-lived request or serverless invocation returns when using the shared module-level client. Use ``shutdown()`` only for final process cleanup or a client that will not be reused. Flush does not stop the background workers or feature flag poller, and does not end open spans. Returning does not guarantee server receipt: pending work can remain after a timeout or span export failure, and failed events may be dropped by consumers. Calls made directly from SDK callbacks such as ``on_error`` are deferred rather than blocking the worker that invoked the callback.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Seconds to wait for event queues to drain, shared across event lanes. Defaults to 10 seconds. Pass ``None`` to wait without a time limit; this does not guarantee successful delivery. Queued spans flush concurrently, waiting up to this many seconds for an in-flight flush before starting a fresh drain budget. A lock wait timeout leaves the in-flight flush to finish. At least one span request is attempted after acquiring the lock, even with no budget left; retriable failures are retried after backoff while budget remains, with one last attempt at the deadline. The last span request is not cut short and is bounded by the client's ``timeout`` in seconds, so this is not a strict wall-clock limit for the whole call. With ``None``, a retriable span failure is left for a later flush rather than retried within this call.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "import posthog\nposthog.capture('event_name', distinct_id='user_id')\n# Before a serverless invocation returns; keep the global client open.\nposthog.flush(timeout_seconds=10)" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "Reads the `evaluation_runtime` each flag definition carries, so no extra request is made. Returns `None` when local evaluation has not loaded a definition for this key. A definition that carries no runtime reports `FeatureFlagEvaluationRuntime.ALL`, the default PostHog applies.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_evaluation_runtime\nruntime = get_feature_flag_evaluation_runtime(\"my-flag\")" - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate.", - "details": "A flag set to `FeatureFlagEvaluationRuntime.ALL` suits either runtime, so it is returned for `CLIENT` and for `SERVER`. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_keys_by_evaluation_runtime\nclient_keys = get_feature_flag_keys_by_evaluation_runtime(FeatureFlagEvaluationRuntime.CLIENT)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and stop the client's background workers. Use `shutdown()` directly in most cases. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Attempt final delivery and permanently shut down the global client. Call this for final process cleanup, not at the end of each request or serverless invocation that shares the module-level client. Use ``flush()`` before returning from those invocations instead. Shutdown closes capture lanes, stops background workers and the feature flag poller, and tears down integrations. The global client is not recreated automatically after shutdown. This normally blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Event draining has no timeout. Queued spans get a final flush with up to 30 seconds waiting for an in-flight flush, then a fresh 30-second drain budget; the last HTTP request is not cut short. Unsent queued spans and still-open spans are discarded with a warning. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. Calls made directly from SDK callbacks such as ``on_error`` are deferred to avoid deadlocking the worker. If blocking completion is required, signal an application-owned thread, return from the callback, and call ``shutdown()`` from that thread. Do not wait inside a callback for another thread or task calling a lifecycle method.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "import posthog\nposthog.traces = {\"service_name\": \"checkout-api\"}\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Tracing", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.81.1.json b/references/posthog-python-references-7.81.1.json deleted file mode 100644 index 2bbfeaef9..000000000 --- a/references/posthog-python-references-7.81.1.json +++ /dev/null @@ -1,3566 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.81.1", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "float" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "float" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "enable_full_ai_capture", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_trace_context", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "traces", - "description": "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.", - "isOptional": true, - "type": "dict" - }, - { - "name": "app_host", - "description": "Your PostHog app host, such as ``https://posthog.example.com``. ``emails`` sends there. Needed only when ``host`` is not PostHog Cloud, for example a reverse proxy, which must not receive the secret key.", - "isOptional": true, - "type": "str" - }, - { - "name": "email_request_timeout_seconds", - "description": "Timeout in seconds for each email send request. Defaults to 15.", - "isOptional": false, - "type": "float" - }, - { - "name": "email_request_max_retries", - "description": "Number of retries for an email send after a network error, a rate limit, or an unavailable service. Defaults to 2. Set to 0 when a job runner already retries the send.", - "isOptional": false, - "type": "int" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to. Falls back to the context distinct ID; the call is dropped with a warning if neither is available.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is queued on an isolated AI lane with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are omitted from the snapshot and listed with a reason in its ``unresolved_flags``.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is True. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Attempt immediate delivery of queued events, ended spans and autocaptured metrics, keeping the client reusable. For a client shared across requests or serverless invocations (including the module-level client), call ``flush()`` before a short-lived invocation returns. Use ``shutdown()`` instead only for final process cleanup or when disposing of a client that will not be reused. Flush does not stop the background workers or feature flag poller, and does not end open spans. Returning does not guarantee server receipt: pending work can remain after a timeout or span export failure, and failed events may be dropped by the consumers. Calls made directly from SDK callbacks such as ``on_error`` are deferred rather than blocking the worker that invoked the callback.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Seconds to wait for event queues to drain, shared across event lanes. Defaults to 10 seconds. Pass ``None`` to wait without a time limit; this does not guarantee successful delivery. Queued spans flush concurrently. The span exporter waits up to this many seconds for an in-flight flush, then uses a fresh drain budget once it acquires the lock. If the lock wait times out, the in-flight flush is left to finish. At least one span request is attempted after acquiring the lock, even with no budget left; retriable failures are retried after backoff while budget remains, with one last attempt at the deadline. Each span request is bounded by the client's ``timeout`` in seconds, and the last request is not cut short. This is therefore not a strict wall-clock limit for the whole call. With ``None``, a retriable span failure is left for a later flush rather than retried within this call.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name', distinct_id='user_id')\n# Before a serverless invocation returns; keep the shared client open.\nposthog.flush(timeout_seconds=10)" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nruntime = posthog.get_feature_flag_evaluation_runtime(\"my-flag\")\nif runtime is FeatureFlagEvaluationRuntime.SERVER:\n ..." - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate. A flag set to ``FeatureFlagEvaluationRuntime.ALL`` suits either runtime, so it is returned for ``CLIENT`` and for ``SERVER``, and asking for ``ALL`` returns every loaded flag. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "The runtime to match, as a ``FeatureFlagEvaluationRuntime`` or its string value.", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nclient_keys = posthog.get_feature_flag_keys_by_evaluation_runtime(\n FeatureFlagEvaluationRuntime.CLIENT\n)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user, preserving valid serialized JSON.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Optional[str]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team'). Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and end the consumer threads. Do not use directly, call `shutdown()` instead. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Attempt final delivery and permanently shut down the client. Call this for final process cleanup or when disposing of a client that will not be reused. It closes capture lanes, stops background workers and the feature flag poller, and tears down integrations. Do not call it at the end of each request or serverless invocation when the client is shared; call ``flush()`` before returning instead. A shut-down client cannot be reused; create a new client if needed. Normally this method blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Event draining has no timeout. Queued spans get one final flush with up to 30 seconds waiting for an in-flight flush, then a fresh 30-second drain budget; the last HTTP request is not cut short. Any spans it cannot send are discarded with a warning, as are spans still open. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. When called directly from an SDK callback such as ``on_error``, shutdown is deferred to avoid blocking the worker that invoked the callback. If the callback must coordinate a blocking shutdown, have it signal an application-owned thread and return before that thread calls shutdown. Do not wait inside the callback for another thread or task that calls a lifecycle method.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span. A forked child starts with no active span; pass the parent span to continue a trace across a fork.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog = Posthog(\"\", traces={\"service_name\": \"checkout-api\"})\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is delivered on an isolated queue with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name, normally one of the `$ai_*` event names. **kwargs: Same optional arguments as `capture()`.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import capture_ai\n\nuuid = capture_ai(\n \"$ai_generation\",\n distinct_id=\"user_123\",\n properties={\"$ai_model\": \"gpt-5\"},\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip. Overriding reserved exception properties through ``properties`` is deprecated and will stop working in the next major version.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation and omit flags that cannot be evaluated locally. The snapshot's ``unresolved_flags`` lists them with a reason.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is ``True``. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Attempt immediate delivery of queued events and ended spans, keeping the global client reusable. Call ``flush()`` before a short-lived request or serverless invocation returns when using the shared module-level client. Use ``shutdown()`` only for final process cleanup or a client that will not be reused. Flush does not stop the background workers or feature flag poller, and does not end open spans. Returning does not guarantee server receipt: pending work can remain after a timeout or span export failure, and failed events may be dropped by consumers. Calls made directly from SDK callbacks such as ``on_error`` are deferred rather than blocking the worker that invoked the callback.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Seconds to wait for event queues to drain, shared across event lanes. Defaults to 10 seconds. Pass ``None`` to wait without a time limit; this does not guarantee successful delivery. Queued spans flush concurrently, waiting up to this many seconds for an in-flight flush before starting a fresh drain budget. A lock wait timeout leaves the in-flight flush to finish. At least one span request is attempted after acquiring the lock, even with no budget left; retriable failures are retried after backoff while budget remains, with one last attempt at the deadline. The last span request is not cut short and is bounded by the client's ``timeout`` in seconds, so this is not a strict wall-clock limit for the whole call. With ``None``, a retriable span failure is left for a later flush rather than retried within this call.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "import posthog\nposthog.capture('event_name', distinct_id='user_id')\n# Before a serverless invocation returns; keep the global client open.\nposthog.flush(timeout_seconds=10)" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "Reads the `evaluation_runtime` each flag definition carries, so no extra request is made. Returns `None` when local evaluation has not loaded a definition for this key. A definition that carries no runtime reports `FeatureFlagEvaluationRuntime.ALL`, the default PostHog applies.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_evaluation_runtime\nruntime = get_feature_flag_evaluation_runtime(\"my-flag\")" - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate.", - "details": "A flag set to `FeatureFlagEvaluationRuntime.ALL` suits either runtime, so it is returned for `CLIENT` and for `SERVER`. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_keys_by_evaluation_runtime\nclient_keys = get_feature_flag_keys_by_evaluation_runtime(FeatureFlagEvaluationRuntime.CLIENT)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and stop the client's background workers. Use `shutdown()` directly in most cases. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Attempt final delivery and permanently shut down the global client. Call this for final process cleanup, not at the end of each request or serverless invocation that shares the module-level client. Use ``flush()`` before returning from those invocations instead. Shutdown closes capture lanes, stops background workers and the feature flag poller, and tears down integrations. The global client is not recreated automatically after shutdown. This normally blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Event draining has no timeout. Queued spans get a final flush with up to 30 seconds waiting for an in-flight flush, then a fresh 30-second drain budget; the last HTTP request is not cut short. Unsent queued spans and still-open spans are discarded with a warning. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. Calls made directly from SDK callbacks such as ``on_error`` are deferred to avoid deadlocking the worker. If blocking completion is required, signal an application-owned thread, return from the callback, and call ``shutdown()`` from that thread. Do not wait inside a callback for another thread or task calling a lifecycle method.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "import posthog\nposthog.traces = {\"service_name\": \"checkout-api\"}\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Tracing", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.82.0.json b/references/posthog-python-references-7.82.0.json deleted file mode 100644 index 8c1c04a60..000000000 --- a/references/posthog-python-references-7.82.0.json +++ /dev/null @@ -1,3566 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.82.0", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "float" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "float" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "enable_full_ai_capture", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_trace_context", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "traces", - "description": "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.", - "isOptional": true, - "type": "dict" - }, - { - "name": "app_host", - "description": "Your PostHog app host, such as ``https://posthog.example.com``. ``emails`` sends there. Needed only when ``host`` is not PostHog Cloud, for example a reverse proxy, which must not receive the secret key.", - "isOptional": true, - "type": "str" - }, - { - "name": "email_request_timeout_seconds", - "description": "Timeout in seconds for each email send request. Defaults to 15.", - "isOptional": false, - "type": "float" - }, - { - "name": "email_request_max_retries", - "description": "Number of retries for an email send after a network error, a rate limit, or an unavailable service. Defaults to 2. Set to 0 when a job runner already retries the send.", - "isOptional": false, - "type": "int" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to. Falls back to the context distinct ID; the call is dropped with a warning if neither is available.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is queued on an isolated AI lane with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are omitted from the snapshot and listed with a reason in its ``unresolved_flags``.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is True. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Attempt immediate delivery of queued events, ended spans and autocaptured metrics, keeping the client reusable. For a client shared across requests or serverless invocations (including the module-level client), call ``flush()`` before a short-lived invocation returns. Use ``shutdown()`` instead only for final process cleanup or when disposing of a client that will not be reused. Flush does not stop the background workers or feature flag poller, and does not end open spans. Returning does not guarantee server receipt: pending work can remain after a timeout or span export failure, and failed events may be dropped by the consumers. Calls made directly from SDK callbacks such as ``on_error`` are deferred rather than blocking the worker that invoked the callback.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Seconds to wait for event queues to drain, shared across event lanes. Defaults to 10 seconds. Pass ``None`` to wait without a time limit; this does not guarantee successful delivery. Queued spans flush concurrently. The span exporter waits up to this many seconds for an in-flight flush, then uses a fresh drain budget once it acquires the lock. If the lock wait times out, the in-flight flush is left to finish. At least one span request is attempted after acquiring the lock, even with no budget left; retriable failures are retried after backoff while budget remains, with one last attempt at the deadline. Each span request is bounded by the client's ``timeout`` in seconds, and the last request is not cut short. This is therefore not a strict wall-clock limit for the whole call. With ``None``, a retriable span failure is left for a later flush rather than retried within this call.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name', distinct_id='user_id')\n# Before a serverless invocation returns; keep the shared client open.\nposthog.flush(timeout_seconds=10)" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nruntime = posthog.get_feature_flag_evaluation_runtime(\"my-flag\")\nif runtime is FeatureFlagEvaluationRuntime.SERVER:\n ..." - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate. A flag set to ``FeatureFlagEvaluationRuntime.ALL`` suits either runtime, so it is returned for ``CLIENT`` and for ``SERVER``, and asking for ``ALL`` returns every loaded flag. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "The runtime to match, as a ``FeatureFlagEvaluationRuntime`` or its string value.", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nclient_keys = posthog.get_feature_flag_keys_by_evaluation_runtime(\n FeatureFlagEvaluationRuntime.CLIENT\n)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user, preserving valid serialized JSON.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Optional[str]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team'). Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and end the consumer threads. Do not use directly, call `shutdown()` instead. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Attempt final delivery and permanently shut down the client. Call this for final process cleanup or when disposing of a client that will not be reused. It closes capture lanes, stops background workers and the feature flag poller, and tears down integrations. Do not call it at the end of each request or serverless invocation when the client is shared; call ``flush()`` before returning instead. A shut-down client cannot be reused; create a new client if needed. Normally this method blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Event draining has no timeout. Queued spans get one final flush with up to 30 seconds waiting for an in-flight flush, then a fresh 30-second drain budget; the last HTTP request is not cut short. Any spans it cannot send are discarded with a warning, as are spans still open. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. When called directly from an SDK callback such as ``on_error``, shutdown is deferred to avoid blocking the worker that invoked the callback. If the callback must coordinate a blocking shutdown, have it signal an application-owned thread and return before that thread calls shutdown. Do not wait inside the callback for another thread or task that calls a lifecycle method.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span. A forked child starts with no active span; pass the parent span to continue a trace across a fork.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog = Posthog(\"\", traces={\"service_name\": \"checkout-api\"})\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is delivered on an isolated queue with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name, normally one of the `$ai_*` event names. **kwargs: Same optional arguments as `capture()`.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import capture_ai\n\nuuid = capture_ai(\n \"$ai_generation\",\n distinct_id=\"user_123\",\n properties={\"$ai_model\": \"gpt-5\"},\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip. Overriding reserved exception properties through ``properties`` is deprecated and will stop working in the next major version.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation and omit flags that cannot be evaluated locally. The snapshot's ``unresolved_flags`` lists them with a reason.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is ``True``. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Attempt immediate delivery of queued events and ended spans, keeping the global client reusable. Call ``flush()`` before a short-lived request or serverless invocation returns when using the shared module-level client. Use ``shutdown()`` only for final process cleanup or a client that will not be reused. Flush does not stop the background workers or feature flag poller, and does not end open spans. Returning does not guarantee server receipt: pending work can remain after a timeout or span export failure, and failed events may be dropped by consumers. Calls made directly from SDK callbacks such as ``on_error`` are deferred rather than blocking the worker that invoked the callback.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Seconds to wait for event queues to drain, shared across event lanes. Defaults to 10 seconds. Pass ``None`` to wait without a time limit; this does not guarantee successful delivery. Queued spans flush concurrently, waiting up to this many seconds for an in-flight flush before starting a fresh drain budget. A lock wait timeout leaves the in-flight flush to finish. At least one span request is attempted after acquiring the lock, even with no budget left; retriable failures are retried after backoff while budget remains, with one last attempt at the deadline. The last span request is not cut short and is bounded by the client's ``timeout`` in seconds, so this is not a strict wall-clock limit for the whole call. With ``None``, a retriable span failure is left for a later flush rather than retried within this call.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "import posthog\nposthog.capture('event_name', distinct_id='user_id')\n# Before a serverless invocation returns; keep the global client open.\nposthog.flush(timeout_seconds=10)" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "Reads the `evaluation_runtime` each flag definition carries, so no extra request is made. Returns `None` when local evaluation has not loaded a definition for this key. A definition that carries no runtime reports `FeatureFlagEvaluationRuntime.ALL`, the default PostHog applies.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_evaluation_runtime\nruntime = get_feature_flag_evaluation_runtime(\"my-flag\")" - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate.", - "details": "A flag set to `FeatureFlagEvaluationRuntime.ALL` suits either runtime, so it is returned for `CLIENT` and for `SERVER`. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_keys_by_evaluation_runtime\nclient_keys = get_feature_flag_keys_by_evaluation_runtime(FeatureFlagEvaluationRuntime.CLIENT)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and stop the client's background workers. Use `shutdown()` directly in most cases. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Attempt final delivery and permanently shut down the global client. Call this for final process cleanup, not at the end of each request or serverless invocation that shares the module-level client. Use ``flush()`` before returning from those invocations instead. Shutdown closes capture lanes, stops background workers and the feature flag poller, and tears down integrations. The global client is not recreated automatically after shutdown. This normally blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Event draining has no timeout. Queued spans get a final flush with up to 30 seconds waiting for an in-flight flush, then a fresh 30-second drain budget; the last HTTP request is not cut short. Unsent queued spans and still-open spans are discarded with a warning. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. Calls made directly from SDK callbacks such as ``on_error`` are deferred to avoid deadlocking the worker. If blocking completion is required, signal an application-owned thread, return from the callback, and call ``shutdown()`` from that thread. Do not wait inside a callback for another thread or task calling a lifecycle method.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "import posthog\nposthog.traces = {\"service_name\": \"checkout-api\"}\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Tracing", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.82.1.json b/references/posthog-python-references-7.82.1.json deleted file mode 100644 index c69506f46..000000000 --- a/references/posthog-python-references-7.82.1.json +++ /dev/null @@ -1,3566 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.82.1", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "float" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "float" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "enable_full_ai_capture", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_trace_context", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "traces", - "description": "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.", - "isOptional": true, - "type": "dict" - }, - { - "name": "app_host", - "description": "Your PostHog app host, such as ``https://posthog.example.com``. ``emails`` sends there. Needed only when ``host`` is not PostHog Cloud, for example a reverse proxy, which must not receive the secret key.", - "isOptional": true, - "type": "str" - }, - { - "name": "email_request_timeout_seconds", - "description": "Timeout in seconds for each email send request. Defaults to 15.", - "isOptional": false, - "type": "float" - }, - { - "name": "email_request_max_retries", - "description": "Number of retries for an email send after a network error, a rate limit, or an unavailable service. Defaults to 2. Set to 0 when a job runner already retries the send.", - "isOptional": false, - "type": "int" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to. Falls back to the context distinct ID; the call is dropped with a warning if neither is available.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is queued on an isolated AI lane with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are omitted from the snapshot and listed with a reason in its ``unresolved_flags``.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is True. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Attempt immediate delivery of queued events, ended spans and autocaptured metrics, keeping the client reusable. For a client shared across requests or serverless invocations (including the module-level client), call ``flush()`` before a short-lived invocation returns. Use ``shutdown()`` instead only for final process cleanup or when disposing of a client that will not be reused. Flush does not stop the background workers or feature flag poller, and does not end open spans. Returning does not guarantee server receipt: pending work can remain after a timeout or span export failure, and failed events may be dropped by the consumers. Calls made directly from SDK callbacks such as ``on_error`` are deferred rather than blocking the worker that invoked the callback.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Seconds to wait for event queues to drain, shared across event lanes. Defaults to 10 seconds. Pass ``None`` to wait without a time limit; this does not guarantee successful delivery. Queued spans flush concurrently. The span exporter waits up to this many seconds for an in-flight flush, then uses a fresh drain budget once it acquires the lock. If the lock wait times out, the in-flight flush is left to finish. At least one span request is attempted after acquiring the lock, even with no budget left; retriable failures are retried after backoff while budget remains, with one last attempt at the deadline. Each span request is bounded by the client's ``timeout`` in seconds, and the last request is not cut short. This is therefore not a strict wall-clock limit for the whole call. With ``None``, a retriable span failure is left for a later flush rather than retried within this call.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name', distinct_id='user_id')\n# Before a serverless invocation returns; keep the shared client open.\nposthog.flush(timeout_seconds=10)" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nruntime = posthog.get_feature_flag_evaluation_runtime(\"my-flag\")\nif runtime is FeatureFlagEvaluationRuntime.SERVER:\n ..." - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate. A flag set to ``FeatureFlagEvaluationRuntime.ALL`` suits either runtime, so it is returned for ``CLIENT`` and for ``SERVER``, and asking for ``ALL`` returns every loaded flag. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "The runtime to match, as a ``FeatureFlagEvaluationRuntime`` or its string value.", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nclient_keys = posthog.get_feature_flag_keys_by_evaluation_runtime(\n FeatureFlagEvaluationRuntime.CLIENT\n)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user, preserving valid serialized JSON.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Optional[str]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team'). Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and end the consumer threads. Do not use directly, call `shutdown()` instead. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Attempt final delivery and permanently shut down the client. Call this for final process cleanup or when disposing of a client that will not be reused. It closes capture lanes, stops background workers and the feature flag poller, and tears down integrations. Do not call it at the end of each request or serverless invocation when the client is shared; call ``flush()`` before returning instead. A shut-down client cannot be reused; create a new client if needed. Normally this method blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Event draining has no timeout. Queued spans get one final flush with up to 30 seconds waiting for an in-flight flush, then a fresh 30-second drain budget; the last HTTP request is not cut short. Any spans it cannot send are discarded with a warning, as are spans still open. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. When called directly from an SDK callback such as ``on_error``, shutdown is deferred to avoid blocking the worker that invoked the callback. If the callback must coordinate a blocking shutdown, have it signal an application-owned thread and return before that thread calls shutdown. Do not wait inside the callback for another thread or task that calls a lifecycle method.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span. A forked child starts with no active span; pass the parent span to continue a trace across a fork.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog = Posthog(\"\", traces={\"service_name\": \"checkout-api\"})\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is delivered on an isolated queue with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name, normally one of the `$ai_*` event names. **kwargs: Same optional arguments as `capture()`.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import capture_ai\n\nuuid = capture_ai(\n \"$ai_generation\",\n distinct_id=\"user_123\",\n properties={\"$ai_model\": \"gpt-5\"},\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip. Overriding reserved exception properties through ``properties`` is deprecated and will stop working in the next major version.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation and omit flags that cannot be evaluated locally. The snapshot's ``unresolved_flags`` lists them with a reason.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is ``True``. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Attempt immediate delivery of queued events and ended spans, keeping the global client reusable. Call ``flush()`` before a short-lived request or serverless invocation returns when using the shared module-level client. Use ``shutdown()`` only for final process cleanup or a client that will not be reused. Flush does not stop the background workers or feature flag poller, and does not end open spans. Returning does not guarantee server receipt: pending work can remain after a timeout or span export failure, and failed events may be dropped by consumers. Calls made directly from SDK callbacks such as ``on_error`` are deferred rather than blocking the worker that invoked the callback.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Seconds to wait for event queues to drain, shared across event lanes. Defaults to 10 seconds. Pass ``None`` to wait without a time limit; this does not guarantee successful delivery. Queued spans flush concurrently, waiting up to this many seconds for an in-flight flush before starting a fresh drain budget. A lock wait timeout leaves the in-flight flush to finish. At least one span request is attempted after acquiring the lock, even with no budget left; retriable failures are retried after backoff while budget remains, with one last attempt at the deadline. The last span request is not cut short and is bounded by the client's ``timeout`` in seconds, so this is not a strict wall-clock limit for the whole call. With ``None``, a retriable span failure is left for a later flush rather than retried within this call.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "import posthog\nposthog.capture('event_name', distinct_id='user_id')\n# Before a serverless invocation returns; keep the global client open.\nposthog.flush(timeout_seconds=10)" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "Reads the `evaluation_runtime` each flag definition carries, so no extra request is made. Returns `None` when local evaluation has not loaded a definition for this key. A definition that carries no runtime reports `FeatureFlagEvaluationRuntime.ALL`, the default PostHog applies.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_evaluation_runtime\nruntime = get_feature_flag_evaluation_runtime(\"my-flag\")" - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate.", - "details": "A flag set to `FeatureFlagEvaluationRuntime.ALL` suits either runtime, so it is returned for `CLIENT` and for `SERVER`. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_keys_by_evaluation_runtime\nclient_keys = get_feature_flag_keys_by_evaluation_runtime(FeatureFlagEvaluationRuntime.CLIENT)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and stop the client's background workers. Use `shutdown()` directly in most cases. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Attempt final delivery and permanently shut down the global client. Call this for final process cleanup, not at the end of each request or serverless invocation that shares the module-level client. Use ``flush()`` before returning from those invocations instead. Shutdown closes capture lanes, stops background workers and the feature flag poller, and tears down integrations. The global client is not recreated automatically after shutdown. This normally blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Event draining has no timeout. Queued spans get a final flush with up to 30 seconds waiting for an in-flight flush, then a fresh 30-second drain budget; the last HTTP request is not cut short. Unsent queued spans and still-open spans are discarded with a warning. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. Calls made directly from SDK callbacks such as ``on_error`` are deferred to avoid deadlocking the worker. If blocking completion is required, signal an application-owned thread, return from the callback, and call ``shutdown()`` from that thread. Do not wait inside a callback for another thread or task calling a lifecycle method.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "import posthog\nposthog.traces = {\"service_name\": \"checkout-api\"}\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Tracing", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.82.2.json b/references/posthog-python-references-7.82.2.json deleted file mode 100644 index 39752929b..000000000 --- a/references/posthog-python-references-7.82.2.json +++ /dev/null @@ -1,3566 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.82.2", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "int", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "int", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "float" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "float" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "enable_full_ai_capture", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_trace_context", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "traces", - "description": "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.", - "isOptional": true, - "type": "dict" - }, - { - "name": "app_host", - "description": "Your PostHog app host, such as ``https://posthog.example.com``. ``emails`` sends there. Needed only when ``host`` is not PostHog Cloud, for example a reverse proxy, which must not receive the secret key.", - "isOptional": true, - "type": "str" - }, - { - "name": "email_request_timeout_seconds", - "description": "Timeout in seconds for each email send request. Defaults to 15.", - "isOptional": false, - "type": "float" - }, - { - "name": "email_request_max_retries", - "description": "Number of retries for an email send after a network error, a rate limit, or an unavailable service. Defaults to 2. Set to 0 when a job runner already retries the send.", - "isOptional": false, - "type": "int" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to. Falls back to the context distinct ID; the call is dropped with a warning if neither is available.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is queued on an isolated AI lane with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are omitted from the snapshot and listed with a reason in its ``unresolved_flags``.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is True. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Attempt immediate delivery of queued events, ended spans and autocaptured metrics, keeping the client reusable. For a client shared across requests or serverless invocations (including the module-level client), call ``flush()`` before a short-lived invocation returns. Use ``shutdown()`` instead only for final process cleanup or when disposing of a client that will not be reused. Flush does not stop the background workers or feature flag poller, and does not end open spans. Returning does not guarantee server receipt: pending work can remain after a timeout or span export failure, and failed events may be dropped by the consumers. Calls made directly from SDK callbacks such as ``on_error`` are deferred rather than blocking the worker that invoked the callback.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Seconds to wait for event queues to drain, shared across event lanes. Defaults to 10 seconds. Pass ``None`` to wait without a time limit; this does not guarantee successful delivery. Queued spans flush concurrently. The span exporter waits up to this many seconds for an in-flight flush, then uses a fresh drain budget once it acquires the lock. If the lock wait times out, the in-flight flush is left to finish. At least one span request is attempted after acquiring the lock, even with no budget left; retriable failures are retried after backoff while budget remains, with one last attempt at the deadline. Each span request is bounded by the client's ``timeout`` in seconds, and the last request is not cut short. This is therefore not a strict wall-clock limit for the whole call. With ``None``, a retriable span failure is left for a later flush rather than retried within this call.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name', distinct_id='user_id')\n# Before a serverless invocation returns; keep the shared client open.\nposthog.flush(timeout_seconds=10)" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nruntime = posthog.get_feature_flag_evaluation_runtime(\"my-flag\")\nif runtime is FeatureFlagEvaluationRuntime.SERVER:\n ..." - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate. A flag set to ``FeatureFlagEvaluationRuntime.ALL`` suits either runtime, so it is returned for ``CLIENT`` and for ``SERVER``, and asking for ``ALL`` returns every loaded flag. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "The runtime to match, as a ``FeatureFlagEvaluationRuntime`` or its string value.", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nclient_keys = posthog.get_feature_flag_keys_by_evaluation_runtime(\n FeatureFlagEvaluationRuntime.CLIENT\n)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user, preserving valid serialized JSON.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Optional[str]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team'). Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and end the consumer threads. Do not use directly, call `shutdown()` instead. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Attempt final delivery and permanently shut down the client. Call this for final process cleanup or when disposing of a client that will not be reused. It closes capture lanes, stops background workers and the feature flag poller, and tears down integrations. Do not call it at the end of each request or serverless invocation when the client is shared; call ``flush()`` before returning instead. A shut-down client cannot be reused; create a new client if needed. Normally this method blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Event draining has no timeout. Queued spans get one final flush with up to 30 seconds waiting for an in-flight flush, then a fresh 30-second drain budget; the last HTTP request is not cut short. Any spans it cannot send are discarded with a warning, as are spans still open. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. When called directly from an SDK callback such as ``on_error``, shutdown is deferred to avoid blocking the worker that invoked the callback. If the callback must coordinate a blocking shutdown, have it signal an application-owned thread and return before that thread calls shutdown. Do not wait inside the callback for another thread or task that calls a lifecycle method.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span. A forked child starts with no active span; pass the parent span to continue a trace across a fork.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog = Posthog(\"\", traces={\"service_name\": \"checkout-api\"})\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is delivered on an isolated queue with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name, normally one of the `$ai_*` event names. **kwargs: Same optional arguments as `capture()`.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import capture_ai\n\nuuid = capture_ai(\n \"$ai_generation\",\n distinct_id=\"user_123\",\n properties={\"$ai_model\": \"gpt-5\"},\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip. Overriding reserved exception properties through ``properties`` is deprecated and will stop working in the next major version.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation and omit flags that cannot be evaluated locally. The snapshot's ``unresolved_flags`` lists them with a reason.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is ``True``. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Attempt immediate delivery of queued events and ended spans, keeping the global client reusable. Call ``flush()`` before a short-lived request or serverless invocation returns when using the shared module-level client. Use ``shutdown()`` only for final process cleanup or a client that will not be reused. Flush does not stop the background workers or feature flag poller, and does not end open spans. Returning does not guarantee server receipt: pending work can remain after a timeout or span export failure, and failed events may be dropped by consumers. Calls made directly from SDK callbacks such as ``on_error`` are deferred rather than blocking the worker that invoked the callback.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Seconds to wait for event queues to drain, shared across event lanes. Defaults to 10 seconds. Pass ``None`` to wait without a time limit; this does not guarantee successful delivery. Queued spans flush concurrently, waiting up to this many seconds for an in-flight flush before starting a fresh drain budget. A lock wait timeout leaves the in-flight flush to finish. At least one span request is attempted after acquiring the lock, even with no budget left; retriable failures are retried after backoff while budget remains, with one last attempt at the deadline. The last span request is not cut short and is bounded by the client's ``timeout`` in seconds, so this is not a strict wall-clock limit for the whole call. With ``None``, a retriable span failure is left for a later flush rather than retried within this call.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "import posthog\nposthog.capture('event_name', distinct_id='user_id')\n# Before a serverless invocation returns; keep the global client open.\nposthog.flush(timeout_seconds=10)" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "Reads the `evaluation_runtime` each flag definition carries, so no extra request is made. Returns `None` when local evaluation has not loaded a definition for this key. A definition that carries no runtime reports `FeatureFlagEvaluationRuntime.ALL`, the default PostHog applies.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_evaluation_runtime\nruntime = get_feature_flag_evaluation_runtime(\"my-flag\")" - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate.", - "details": "A flag set to `FeatureFlagEvaluationRuntime.ALL` suits either runtime, so it is returned for `CLIENT` and for `SERVER`. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_keys_by_evaluation_runtime\nclient_keys = get_feature_flag_keys_by_evaluation_runtime(FeatureFlagEvaluationRuntime.CLIENT)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and stop the client's background workers. Use `shutdown()` directly in most cases. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Attempt final delivery and permanently shut down the global client. Call this for final process cleanup, not at the end of each request or serverless invocation that shares the module-level client. Use ``flush()`` before returning from those invocations instead. Shutdown closes capture lanes, stops background workers and the feature flag poller, and tears down integrations. The global client is not recreated automatically after shutdown. This normally blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Event draining has no timeout. Queued spans get a final flush with up to 30 seconds waiting for an in-flight flush, then a fresh 30-second drain budget; the last HTTP request is not cut short. Unsent queued spans and still-open spans are discarded with a warning. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. Calls made directly from SDK callbacks such as ``on_error`` are deferred to avoid deadlocking the worker. If blocking completion is required, signal an application-owned thread, return from the callback, and call ``shutdown()`` from that thread. Do not wait inside a callback for another thread or task calling a lifecycle method.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "import posthog\nposthog.traces = {\"service_name\": \"checkout-api\"}\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Tracing", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.83.0.json b/references/posthog-python-references-7.83.0.json deleted file mode 100644 index ea89d2637..000000000 --- a/references/posthog-python-references-7.83.0.json +++ /dev/null @@ -1,3566 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.83.0", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "Optional[int]", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "Optional[int]", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "float" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "float" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "enable_full_ai_capture", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_trace_context", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "traces", - "description": "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.", - "isOptional": true, - "type": "dict" - }, - { - "name": "app_host", - "description": "Your PostHog app host, such as ``https://posthog.example.com``. ``emails`` sends there. Needed only when ``host`` is not PostHog Cloud, for example a reverse proxy, which must not receive the secret key.", - "isOptional": true, - "type": "str" - }, - { - "name": "email_request_timeout_seconds", - "description": "Timeout in seconds for each email send request. Defaults to 15.", - "isOptional": false, - "type": "float" - }, - { - "name": "email_request_max_retries", - "description": "Number of retries for an email send after a network error, a rate limit, or an unavailable service. Defaults to 2. Set to 0 when a job runner already retries the send.", - "isOptional": false, - "type": "int" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to. Falls back to the context distinct ID; the call is dropped with a warning if neither is available.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is queued on an isolated AI lane with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are omitted from the snapshot and listed with a reason in its ``unresolved_flags``.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is True. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Attempt immediate delivery of queued events, ended spans and autocaptured metrics, keeping the client reusable. For a client shared across requests or serverless invocations (including the module-level client), call ``flush()`` before a short-lived invocation returns. Use ``shutdown()`` instead only for final process cleanup or when disposing of a client that will not be reused. Flush does not stop the background workers or feature flag poller, and does not end open spans. Returning does not guarantee server receipt: pending work can remain after a timeout or span export failure, and failed events may be dropped by the consumers. Calls made directly from SDK callbacks such as ``on_error`` are deferred rather than blocking the worker that invoked the callback.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Seconds to wait for event queues to drain, shared across event lanes. Defaults to 10 seconds. Pass ``None`` to wait without a time limit; this does not guarantee successful delivery. Queued spans flush concurrently. The span exporter waits up to this many seconds for an in-flight flush, then uses a fresh drain budget once it acquires the lock. If the lock wait times out, the in-flight flush is left to finish. At least one span request is attempted after acquiring the lock, even with no budget left; retriable failures are retried after backoff while budget remains, with one last attempt at the deadline. Each span request is bounded by the client's ``timeout`` in seconds, and the last request is not cut short. This is therefore not a strict wall-clock limit for the whole call. With ``None``, a retriable span failure is left for a later flush rather than retried within this call.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name', distinct_id='user_id')\n# Before a serverless invocation returns; keep the shared client open.\nposthog.flush(timeout_seconds=10)" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nruntime = posthog.get_feature_flag_evaluation_runtime(\"my-flag\")\nif runtime is FeatureFlagEvaluationRuntime.SERVER:\n ..." - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate. A flag set to ``FeatureFlagEvaluationRuntime.ALL`` suits either runtime, so it is returned for ``CLIENT`` and for ``SERVER``, and asking for ``ALL`` returns every loaded flag. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "The runtime to match, as a ``FeatureFlagEvaluationRuntime`` or its string value.", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nclient_keys = posthog.get_feature_flag_keys_by_evaluation_runtime(\n FeatureFlagEvaluationRuntime.CLIENT\n)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user, preserving valid serialized JSON.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Optional[str]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team'). Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and end the consumer threads. Do not use directly, call `shutdown()` instead. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Attempt final delivery and permanently shut down the client. Call this for final process cleanup or when disposing of a client that will not be reused. It closes capture lanes, stops background workers and the feature flag poller, and tears down integrations. Do not call it at the end of each request or serverless invocation when the client is shared; call ``flush()`` before returning instead. A shut-down client cannot be reused; create a new client if needed. Normally this method blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Event draining has no timeout. Queued spans get one final flush with up to 30 seconds waiting for an in-flight flush, then a fresh 30-second drain budget; the last HTTP request is not cut short. Any spans it cannot send are discarded with a warning, as are spans still open. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. When called directly from an SDK callback such as ``on_error``, shutdown is deferred to avoid blocking the worker that invoked the callback. If the callback must coordinate a blocking shutdown, have it signal an application-owned thread and return before that thread calls shutdown. Do not wait inside the callback for another thread or task that calls a lifecycle method.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span. A forked child starts with no active span; pass the parent span to continue a trace across a fork.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog = Posthog(\"\", traces={\"service_name\": \"checkout-api\"})\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is delivered on an isolated queue with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name, normally one of the `$ai_*` event names. **kwargs: Same optional arguments as `capture()`.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import capture_ai\n\nuuid = capture_ai(\n \"$ai_generation\",\n distinct_id=\"user_123\",\n properties={\"$ai_model\": \"gpt-5\"},\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip. Overriding reserved exception properties through ``properties`` is deprecated and will stop working in the next major version.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation and omit flags that cannot be evaluated locally. The snapshot's ``unresolved_flags`` lists them with a reason.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is ``True``. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Attempt immediate delivery of queued events and ended spans, keeping the global client reusable. Call ``flush()`` before a short-lived request or serverless invocation returns when using the shared module-level client. Use ``shutdown()`` only for final process cleanup or a client that will not be reused. Flush does not stop the background workers or feature flag poller, and does not end open spans. Returning does not guarantee server receipt: pending work can remain after a timeout or span export failure, and failed events may be dropped by consumers. Calls made directly from SDK callbacks such as ``on_error`` are deferred rather than blocking the worker that invoked the callback.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Seconds to wait for event queues to drain, shared across event lanes. Defaults to 10 seconds. Pass ``None`` to wait without a time limit; this does not guarantee successful delivery. Queued spans flush concurrently, waiting up to this many seconds for an in-flight flush before starting a fresh drain budget. A lock wait timeout leaves the in-flight flush to finish. At least one span request is attempted after acquiring the lock, even with no budget left; retriable failures are retried after backoff while budget remains, with one last attempt at the deadline. The last span request is not cut short and is bounded by the client's ``timeout`` in seconds, so this is not a strict wall-clock limit for the whole call. With ``None``, a retriable span failure is left for a later flush rather than retried within this call.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "import posthog\nposthog.capture('event_name', distinct_id='user_id')\n# Before a serverless invocation returns; keep the global client open.\nposthog.flush(timeout_seconds=10)" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "Reads the `evaluation_runtime` each flag definition carries, so no extra request is made. Returns `None` when local evaluation has not loaded a definition for this key. A definition that carries no runtime reports `FeatureFlagEvaluationRuntime.ALL`, the default PostHog applies.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_evaluation_runtime\nruntime = get_feature_flag_evaluation_runtime(\"my-flag\")" - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate.", - "details": "A flag set to `FeatureFlagEvaluationRuntime.ALL` suits either runtime, so it is returned for `CLIENT` and for `SERVER`. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_keys_by_evaluation_runtime\nclient_keys = get_feature_flag_keys_by_evaluation_runtime(FeatureFlagEvaluationRuntime.CLIENT)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and stop the client's background workers. Use `shutdown()` directly in most cases. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Attempt final delivery and permanently shut down the global client. Call this for final process cleanup, not at the end of each request or serverless invocation that shares the module-level client. Use ``flush()`` before returning from those invocations instead. Shutdown closes capture lanes, stops background workers and the feature flag poller, and tears down integrations. The global client is not recreated automatically after shutdown. This normally blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Event draining has no timeout. Queued spans get a final flush with up to 30 seconds waiting for an in-flight flush, then a fresh 30-second drain budget; the last HTTP request is not cut short. Unsent queued spans and still-open spans are discarded with a warning. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. Calls made directly from SDK callbacks such as ``on_error`` are deferred to avoid deadlocking the worker. If blocking completion is required, signal an application-owned thread, return from the callback, and call ``shutdown()`` from that thread. Do not wait inside a callback for another thread or task calling a lifecycle method.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "import posthog\nposthog.traces = {\"service_name\": \"checkout-api\"}\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Tracing", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.83.1.json b/references/posthog-python-references-7.83.1.json deleted file mode 100644 index a2d0c5a3e..000000000 --- a/references/posthog-python-references-7.83.1.json +++ /dev/null @@ -1,3566 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.83.1", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "Optional[int]", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "Optional[int]", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "float" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "float" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "enable_full_ai_capture", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_trace_context", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "traces", - "description": "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.", - "isOptional": true, - "type": "dict" - }, - { - "name": "app_host", - "description": "Your PostHog app host, such as ``https://posthog.example.com``. ``emails`` sends there. Needed only when ``host`` is not PostHog Cloud, for example a reverse proxy, which must not receive the secret key.", - "isOptional": true, - "type": "str" - }, - { - "name": "email_request_timeout_seconds", - "description": "Timeout in seconds for each email send request. Defaults to 15.", - "isOptional": false, - "type": "float" - }, - { - "name": "email_request_max_retries", - "description": "Number of retries for an email send after a network error, a rate limit, or an unavailable service. Defaults to 2. Set to 0 when a job runner already retries the send.", - "isOptional": false, - "type": "int" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to. Falls back to the context distinct ID; the call is dropped with a warning if neither is available.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is queued on an isolated AI lane with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are omitted from the snapshot and listed with a reason in its ``unresolved_flags``.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is True. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Attempt immediate delivery of queued events, ended spans and autocaptured metrics, keeping the client reusable. For a client shared across requests or serverless invocations (including the module-level client), call ``flush()`` before a short-lived invocation returns. Use ``shutdown()`` instead only for final process cleanup or when disposing of a client that will not be reused. Flush does not stop the background workers or feature flag poller, and does not end open spans. Returning does not guarantee server receipt: pending work can remain after a timeout or span export failure, and failed events may be dropped by the consumers. Calls made directly from SDK callbacks such as ``on_error`` are deferred rather than blocking the worker that invoked the callback.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Seconds to wait for event queues to drain, shared across event lanes. Defaults to 10 seconds. Pass ``None`` to wait without a time limit; this does not guarantee successful delivery. Queued spans flush concurrently. The span exporter waits up to this many seconds for an in-flight flush, then uses a fresh drain budget once it acquires the lock. If the lock wait times out, the in-flight flush is left to finish. At least one span request is attempted after acquiring the lock, even with no budget left; retriable failures are retried after backoff while budget remains, with one last attempt at the deadline. Each span request is bounded by the client's ``timeout`` in seconds, and the last request is not cut short. This is therefore not a strict wall-clock limit for the whole call. With ``None``, a retriable span failure is left for a later flush rather than retried within this call.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name', distinct_id='user_id')\n# Before a serverless invocation returns; keep the shared client open.\nposthog.flush(timeout_seconds=10)" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nruntime = posthog.get_feature_flag_evaluation_runtime(\"my-flag\")\nif runtime is FeatureFlagEvaluationRuntime.SERVER:\n ..." - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate. A flag set to ``FeatureFlagEvaluationRuntime.ALL`` suits either runtime, so it is returned for ``CLIENT`` and for ``SERVER``, and asking for ``ALL`` returns every loaded flag. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "The runtime to match, as a ``FeatureFlagEvaluationRuntime`` or its string value.", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nclient_keys = posthog.get_feature_flag_keys_by_evaluation_runtime(\n FeatureFlagEvaluationRuntime.CLIENT\n)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user, preserving valid serialized JSON.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Optional[str]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team'). Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and end the consumer threads. Do not use directly, call `shutdown()` instead. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Attempt final delivery and permanently shut down the client. Call this for final process cleanup or when disposing of a client that will not be reused. It closes capture lanes, stops background workers and the feature flag poller, and tears down integrations. Do not call it at the end of each request or serverless invocation when the client is shared; call ``flush()`` before returning instead. A shut-down client cannot be reused; create a new client if needed. Normally this method blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Event draining has no timeout. Queued spans get one final flush with up to 30 seconds waiting for an in-flight flush, then a fresh 30-second drain budget; the last HTTP request is not cut short. Any spans it cannot send are discarded with a warning, as are spans still open. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. When called directly from an SDK callback such as ``on_error``, shutdown is deferred to avoid blocking the worker that invoked the callback. If the callback must coordinate a blocking shutdown, have it signal an application-owned thread and return before that thread calls shutdown. Do not wait inside the callback for another thread or task that calls a lifecycle method.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span. A forked child starts with no active span; pass the parent span to continue a trace across a fork.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog = Posthog(\"\", traces={\"service_name\": \"checkout-api\"})\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is delivered on an isolated queue with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name, normally one of the `$ai_*` event names. **kwargs: Same optional arguments as `capture()`.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import capture_ai\n\nuuid = capture_ai(\n \"$ai_generation\",\n distinct_id=\"user_123\",\n properties={\"$ai_model\": \"gpt-5\"},\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip. Overriding reserved exception properties through ``properties`` is deprecated and will stop working in the next major version.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation and omit flags that cannot be evaluated locally. The snapshot's ``unresolved_flags`` lists them with a reason.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is ``True``. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Attempt immediate delivery of queued events and ended spans, keeping the global client reusable. Call ``flush()`` before a short-lived request or serverless invocation returns when using the shared module-level client. Use ``shutdown()`` only for final process cleanup or a client that will not be reused. Flush does not stop the background workers or feature flag poller, and does not end open spans. Returning does not guarantee server receipt: pending work can remain after a timeout or span export failure, and failed events may be dropped by consumers. Calls made directly from SDK callbacks such as ``on_error`` are deferred rather than blocking the worker that invoked the callback.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Seconds to wait for event queues to drain, shared across event lanes. Defaults to 10 seconds. Pass ``None`` to wait without a time limit; this does not guarantee successful delivery. Queued spans flush concurrently, waiting up to this many seconds for an in-flight flush before starting a fresh drain budget. A lock wait timeout leaves the in-flight flush to finish. At least one span request is attempted after acquiring the lock, even with no budget left; retriable failures are retried after backoff while budget remains, with one last attempt at the deadline. The last span request is not cut short and is bounded by the client's ``timeout`` in seconds, so this is not a strict wall-clock limit for the whole call. With ``None``, a retriable span failure is left for a later flush rather than retried within this call.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "import posthog\nposthog.capture('event_name', distinct_id='user_id')\n# Before a serverless invocation returns; keep the global client open.\nposthog.flush(timeout_seconds=10)" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "Reads the `evaluation_runtime` each flag definition carries, so no extra request is made. Returns `None` when local evaluation has not loaded a definition for this key. A definition that carries no runtime reports `FeatureFlagEvaluationRuntime.ALL`, the default PostHog applies.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_evaluation_runtime\nruntime = get_feature_flag_evaluation_runtime(\"my-flag\")" - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate.", - "details": "A flag set to `FeatureFlagEvaluationRuntime.ALL` suits either runtime, so it is returned for `CLIENT` and for `SERVER`. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_keys_by_evaluation_runtime\nclient_keys = get_feature_flag_keys_by_evaluation_runtime(FeatureFlagEvaluationRuntime.CLIENT)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and stop the client's background workers. Use `shutdown()` directly in most cases. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Attempt final delivery and permanently shut down the global client. Call this for final process cleanup, not at the end of each request or serverless invocation that shares the module-level client. Use ``flush()`` before returning from those invocations instead. Shutdown closes capture lanes, stops background workers and the feature flag poller, and tears down integrations. The global client is not recreated automatically after shutdown. This normally blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Event draining has no timeout. Queued spans get a final flush with up to 30 seconds waiting for an in-flight flush, then a fresh 30-second drain budget; the last HTTP request is not cut short. Unsent queued spans and still-open spans are discarded with a warning. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. Calls made directly from SDK callbacks such as ``on_error`` are deferred to avoid deadlocking the worker. If blocking completion is required, signal an application-owned thread, return from the callback, and call ``shutdown()`` from that thread. Do not wait inside a callback for another thread or task calling a lifecycle method.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "import posthog\nposthog.traces = {\"service_name\": \"checkout-api\"}\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Tracing", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.83.2.json b/references/posthog-python-references-7.83.2.json deleted file mode 100644 index 8962f1f55..000000000 --- a/references/posthog-python-references-7.83.2.json +++ /dev/null @@ -1,3566 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.83.2", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "Optional[int]", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "Optional[int]", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "float" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "float" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "enable_full_ai_capture", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_trace_context", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "traces", - "description": "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.", - "isOptional": true, - "type": "dict" - }, - { - "name": "app_host", - "description": "Your PostHog app host, such as ``https://posthog.example.com``. ``emails`` sends there. Needed only when ``host`` is not PostHog Cloud, for example a reverse proxy, which must not receive the secret key.", - "isOptional": true, - "type": "str" - }, - { - "name": "email_request_timeout_seconds", - "description": "Timeout in seconds for each email send request. Defaults to 15.", - "isOptional": false, - "type": "float" - }, - { - "name": "email_request_max_retries", - "description": "Number of retries for an email send after a network error, a rate limit, or an unavailable service. Defaults to 2. Set to 0 when a job runner already retries the send.", - "isOptional": false, - "type": "int" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to. Falls back to the context distinct ID; the call is dropped with a warning if neither is available.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is queued on an isolated AI lane with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are omitted from the snapshot and listed with a reason in its ``unresolved_flags``.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is True. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Attempt immediate delivery of queued events, ended spans and autocaptured metrics, keeping the client reusable. For a client shared across requests or serverless invocations (including the module-level client), call ``flush()`` before a short-lived invocation returns. Use ``shutdown()`` instead only for final process cleanup or when disposing of a client that will not be reused. Flush does not stop the background workers or feature flag poller, and does not end open spans. Returning does not guarantee server receipt: pending work can remain after a timeout or span export failure, and failed events may be dropped by the consumers. Calls made directly from SDK callbacks such as ``on_error`` are deferred rather than blocking the worker that invoked the callback.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Seconds to wait for event queues to drain, shared across event lanes. Defaults to 10 seconds. Pass ``None`` to wait without a time limit; this does not guarantee successful delivery. Queued spans flush concurrently. The span exporter waits up to this many seconds for an in-flight flush, then uses a fresh drain budget once it acquires the lock. If the lock wait times out, the in-flight flush is left to finish. At least one span request is attempted after acquiring the lock, even with no budget left; retriable failures are retried after backoff while budget remains, with one last attempt at the deadline. Each span request is bounded by the client's ``timeout`` in seconds, and the last request is not cut short. This is therefore not a strict wall-clock limit for the whole call. With ``None``, a retriable span failure is left for a later flush rather than retried within this call.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name', distinct_id='user_id')\n# Before a serverless invocation returns; keep the shared client open.\nposthog.flush(timeout_seconds=10)" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nruntime = posthog.get_feature_flag_evaluation_runtime(\"my-flag\")\nif runtime is FeatureFlagEvaluationRuntime.SERVER:\n ..." - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate. A flag set to ``FeatureFlagEvaluationRuntime.ALL`` suits either runtime, so it is returned for ``CLIENT`` and for ``SERVER``, and asking for ``ALL`` returns every loaded flag. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "The runtime to match, as a ``FeatureFlagEvaluationRuntime`` or its string value.", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nclient_keys = posthog.get_feature_flag_keys_by_evaluation_runtime(\n FeatureFlagEvaluationRuntime.CLIENT\n)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user, preserving valid serialized JSON.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Optional[str]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team'). Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and end the consumer threads. Do not use directly, call `shutdown()` instead. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Attempt final delivery and permanently shut down the client. Call this for final process cleanup or when disposing of a client that will not be reused. It closes capture lanes, stops background workers and the feature flag poller, and tears down integrations. Do not call it at the end of each request or serverless invocation when the client is shared; call ``flush()`` before returning instead. A shut-down client cannot be reused; create a new client if needed. Normally this method blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Event draining has no timeout. Queued spans get one final flush with up to 30 seconds waiting for an in-flight flush, then a fresh 30-second drain budget; the last HTTP request is not cut short. Any spans it cannot send are discarded with a warning, as are spans still open. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. When called directly from an SDK callback such as ``on_error``, shutdown is deferred to avoid blocking the worker that invoked the callback. If the callback must coordinate a blocking shutdown, have it signal an application-owned thread and return before that thread calls shutdown. Do not wait inside the callback for another thread or task that calls a lifecycle method.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span. A forked child starts with no active span; pass the parent span to continue a trace across a fork.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog = Posthog(\"\", traces={\"service_name\": \"checkout-api\"})\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is delivered on an isolated queue with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name, normally one of the `$ai_*` event names. **kwargs: Same optional arguments as `capture()`.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import capture_ai\n\nuuid = capture_ai(\n \"$ai_generation\",\n distinct_id=\"user_123\",\n properties={\"$ai_model\": \"gpt-5\"},\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip. Overriding reserved exception properties through ``properties`` is deprecated and will stop working in the next major version.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation and omit flags that cannot be evaluated locally. The snapshot's ``unresolved_flags`` lists them with a reason.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is ``True``. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Attempt immediate delivery of queued events and ended spans, keeping the global client reusable. Call ``flush()`` before a short-lived request or serverless invocation returns when using the shared module-level client. Use ``shutdown()`` only for final process cleanup or a client that will not be reused. Flush does not stop the background workers or feature flag poller, and does not end open spans. Returning does not guarantee server receipt: pending work can remain after a timeout or span export failure, and failed events may be dropped by consumers. Calls made directly from SDK callbacks such as ``on_error`` are deferred rather than blocking the worker that invoked the callback.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Seconds to wait for event queues to drain, shared across event lanes. Defaults to 10 seconds. Pass ``None`` to wait without a time limit; this does not guarantee successful delivery. Queued spans flush concurrently, waiting up to this many seconds for an in-flight flush before starting a fresh drain budget. A lock wait timeout leaves the in-flight flush to finish. At least one span request is attempted after acquiring the lock, even with no budget left; retriable failures are retried after backoff while budget remains, with one last attempt at the deadline. The last span request is not cut short and is bounded by the client's ``timeout`` in seconds, so this is not a strict wall-clock limit for the whole call. With ``None``, a retriable span failure is left for a later flush rather than retried within this call.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "import posthog\nposthog.capture('event_name', distinct_id='user_id')\n# Before a serverless invocation returns; keep the global client open.\nposthog.flush(timeout_seconds=10)" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "Reads the `evaluation_runtime` each flag definition carries, so no extra request is made. Returns `None` when local evaluation has not loaded a definition for this key. A definition that carries no runtime reports `FeatureFlagEvaluationRuntime.ALL`, the default PostHog applies.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_evaluation_runtime\nruntime = get_feature_flag_evaluation_runtime(\"my-flag\")" - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate.", - "details": "A flag set to `FeatureFlagEvaluationRuntime.ALL` suits either runtime, so it is returned for `CLIENT` and for `SERVER`. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_keys_by_evaluation_runtime\nclient_keys = get_feature_flag_keys_by_evaluation_runtime(FeatureFlagEvaluationRuntime.CLIENT)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and stop the client's background workers. Use `shutdown()` directly in most cases. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Attempt final delivery and permanently shut down the global client. Call this for final process cleanup, not at the end of each request or serverless invocation that shares the module-level client. Use ``flush()`` before returning from those invocations instead. Shutdown closes capture lanes, stops background workers and the feature flag poller, and tears down integrations. The global client is not recreated automatically after shutdown. This normally blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Event draining has no timeout. Queued spans get a final flush with up to 30 seconds waiting for an in-flight flush, then a fresh 30-second drain budget; the last HTTP request is not cut short. Unsent queued spans and still-open spans are discarded with a warning. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. Calls made directly from SDK callbacks such as ``on_error`` are deferred to avoid deadlocking the worker. If blocking completion is required, signal an application-owned thread, return from the callback, and call ``shutdown()`` from that thread. Do not wait inside a callback for another thread or task calling a lifecycle method.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "import posthog\nposthog.traces = {\"service_name\": \"checkout-api\"}\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Tracing", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.84.0.json b/references/posthog-python-references-7.84.0.json deleted file mode 100644 index d02a4ee15..000000000 --- a/references/posthog-python-references-7.84.0.json +++ /dev/null @@ -1,3572 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.84.0", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "Optional[int]", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "Optional[int]", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "float" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "float" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "enable_full_ai_capture", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_trace_context", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "traces", - "description": "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.", - "isOptional": true, - "type": "dict" - }, - { - "name": "app_host", - "description": "Your PostHog app host, such as ``https://posthog.example.com``. ``emails`` sends there. Needed only when ``host`` is not PostHog Cloud, for example a reverse proxy, which must not receive the secret key.", - "isOptional": true, - "type": "str" - }, - { - "name": "email_request_timeout_seconds", - "description": "Timeout in seconds for each email send request. Defaults to 15.", - "isOptional": false, - "type": "float" - }, - { - "name": "email_request_max_retries", - "description": "Number of retries for an email send after a network error, a rate limit, or an unavailable service. Defaults to 2. Set to 0 when a job runner already retries the send.", - "isOptional": false, - "type": "int" - }, - { - "name": "migrated_from", - "description": "The email provider you moved from, such as ``\"resend\"``. ``emails`` sends it with every request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to. Falls back to the context distinct ID; the call is dropped with a warning if neither is available.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is queued on an isolated AI lane with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are omitted from the snapshot and listed with a reason in its ``unresolved_flags``.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is True. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Attempt immediate delivery of queued events, ended spans and autocaptured metrics, keeping the client reusable. For a client shared across requests or serverless invocations (including the module-level client), call ``flush()`` before a short-lived invocation returns. Use ``shutdown()`` instead only for final process cleanup or when disposing of a client that will not be reused. Flush does not stop the background workers or feature flag poller, and does not end open spans. Returning does not guarantee server receipt: pending work can remain after a timeout or span export failure, and failed events may be dropped by the consumers. Calls made directly from SDK callbacks such as ``on_error`` are deferred rather than blocking the worker that invoked the callback.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Seconds to wait for event queues to drain, shared across event lanes. Defaults to 10 seconds. Pass ``None`` to wait without a time limit; this does not guarantee successful delivery. Queued spans flush concurrently. The span exporter waits up to this many seconds for an in-flight flush, then uses a fresh drain budget once it acquires the lock. If the lock wait times out, the in-flight flush is left to finish. At least one span request is attempted after acquiring the lock, even with no budget left; retriable failures are retried after backoff while budget remains, with one last attempt at the deadline. Each span request is bounded by the client's ``timeout`` in seconds, and the last request is not cut short. This is therefore not a strict wall-clock limit for the whole call. With ``None``, a retriable span failure is left for a later flush rather than retried within this call.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name', distinct_id='user_id')\n# Before a serverless invocation returns; keep the shared client open.\nposthog.flush(timeout_seconds=10)" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nruntime = posthog.get_feature_flag_evaluation_runtime(\"my-flag\")\nif runtime is FeatureFlagEvaluationRuntime.SERVER:\n ..." - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate. A flag set to ``FeatureFlagEvaluationRuntime.ALL`` suits either runtime, so it is returned for ``CLIENT`` and for ``SERVER``, and asking for ``ALL`` returns every loaded flag. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "The runtime to match, as a ``FeatureFlagEvaluationRuntime`` or its string value.", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nclient_keys = posthog.get_feature_flag_keys_by_evaluation_runtime(\n FeatureFlagEvaluationRuntime.CLIENT\n)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user, preserving valid serialized JSON.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Optional[str]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team'). Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and end the consumer threads. Do not use directly, call `shutdown()` instead. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Attempt final delivery and permanently shut down the client. Call this for final process cleanup or when disposing of a client that will not be reused. It closes capture lanes, stops background workers and the feature flag poller, and tears down integrations. Do not call it at the end of each request or serverless invocation when the client is shared; call ``flush()`` before returning instead. A shut-down client cannot be reused; create a new client if needed. Normally this method blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Event draining has no timeout. Queued spans get one final flush with up to 30 seconds waiting for an in-flight flush, then a fresh 30-second drain budget; the last HTTP request is not cut short. Any spans it cannot send are discarded with a warning, as are spans still open. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. When called directly from an SDK callback such as ``on_error``, shutdown is deferred to avoid blocking the worker that invoked the callback. If the callback must coordinate a blocking shutdown, have it signal an application-owned thread and return before that thread calls shutdown. Do not wait inside the callback for another thread or task that calls a lifecycle method.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span. A forked child starts with no active span; pass the parent span to continue a trace across a fork.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog = Posthog(\"\", traces={\"service_name\": \"checkout-api\"})\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is delivered on an isolated queue with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name, normally one of the `$ai_*` event names. **kwargs: Same optional arguments as `capture()`.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import capture_ai\n\nuuid = capture_ai(\n \"$ai_generation\",\n distinct_id=\"user_123\",\n properties={\"$ai_model\": \"gpt-5\"},\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip. Overriding reserved exception properties through ``properties`` is deprecated and will stop working in the next major version.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation and omit flags that cannot be evaluated locally. The snapshot's ``unresolved_flags`` lists them with a reason.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is ``True``. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Attempt immediate delivery of queued events and ended spans, keeping the global client reusable. Call ``flush()`` before a short-lived request or serverless invocation returns when using the shared module-level client. Use ``shutdown()`` only for final process cleanup or a client that will not be reused. Flush does not stop the background workers or feature flag poller, and does not end open spans. Returning does not guarantee server receipt: pending work can remain after a timeout or span export failure, and failed events may be dropped by consumers. Calls made directly from SDK callbacks such as ``on_error`` are deferred rather than blocking the worker that invoked the callback.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Seconds to wait for event queues to drain, shared across event lanes. Defaults to 10 seconds. Pass ``None`` to wait without a time limit; this does not guarantee successful delivery. Queued spans flush concurrently, waiting up to this many seconds for an in-flight flush before starting a fresh drain budget. A lock wait timeout leaves the in-flight flush to finish. At least one span request is attempted after acquiring the lock, even with no budget left; retriable failures are retried after backoff while budget remains, with one last attempt at the deadline. The last span request is not cut short and is bounded by the client's ``timeout`` in seconds, so this is not a strict wall-clock limit for the whole call. With ``None``, a retriable span failure is left for a later flush rather than retried within this call.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "import posthog\nposthog.capture('event_name', distinct_id='user_id')\n# Before a serverless invocation returns; keep the global client open.\nposthog.flush(timeout_seconds=10)" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "Reads the `evaluation_runtime` each flag definition carries, so no extra request is made. Returns `None` when local evaluation has not loaded a definition for this key. A definition that carries no runtime reports `FeatureFlagEvaluationRuntime.ALL`, the default PostHog applies.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_evaluation_runtime\nruntime = get_feature_flag_evaluation_runtime(\"my-flag\")" - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate.", - "details": "A flag set to `FeatureFlagEvaluationRuntime.ALL` suits either runtime, so it is returned for `CLIENT` and for `SERVER`. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_keys_by_evaluation_runtime\nclient_keys = get_feature_flag_keys_by_evaluation_runtime(FeatureFlagEvaluationRuntime.CLIENT)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and stop the client's background workers. Use `shutdown()` directly in most cases. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Attempt final delivery and permanently shut down the global client. Call this for final process cleanup, not at the end of each request or serverless invocation that shares the module-level client. Use ``flush()`` before returning from those invocations instead. Shutdown closes capture lanes, stops background workers and the feature flag poller, and tears down integrations. The global client is not recreated automatically after shutdown. This normally blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Event draining has no timeout. Queued spans get a final flush with up to 30 seconds waiting for an in-flight flush, then a fresh 30-second drain budget; the last HTTP request is not cut short. Unsent queued spans and still-open spans are discarded with a warning. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. Calls made directly from SDK callbacks such as ``on_error`` are deferred to avoid deadlocking the worker. If blocking completion is required, signal an application-owned thread, return from the callback, and call ``shutdown()`` from that thread. Do not wait inside a callback for another thread or task calling a lifecycle method.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "import posthog\nposthog.traces = {\"service_name\": \"checkout-api\"}\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Tracing", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.84.1.json b/references/posthog-python-references-7.84.1.json deleted file mode 100644 index 0da4e84b5..000000000 --- a/references/posthog-python-references-7.84.1.json +++ /dev/null @@ -1,3572 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.84.1", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "Optional[int]", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "Optional[int]", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "float" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "float" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "enable_full_ai_capture", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_trace_context", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "traces", - "description": "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.", - "isOptional": true, - "type": "dict" - }, - { - "name": "app_host", - "description": "Your PostHog app host, such as ``https://posthog.example.com``. ``emails`` sends there. Needed only when ``host`` is not PostHog Cloud, for example a reverse proxy, which must not receive the secret key.", - "isOptional": true, - "type": "str" - }, - { - "name": "email_request_timeout_seconds", - "description": "Timeout in seconds for each email send request. Defaults to 15.", - "isOptional": false, - "type": "float" - }, - { - "name": "email_request_max_retries", - "description": "Number of retries for an email send after a network error, a rate limit, or an unavailable service. Defaults to 2. Set to 0 when a job runner already retries the send.", - "isOptional": false, - "type": "int" - }, - { - "name": "migrated_from", - "description": "The email provider you moved from, such as ``\"resend\"``. ``emails`` sends it with every request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to. Falls back to the context distinct ID; the call is dropped with a warning if neither is available.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is queued on an isolated AI lane with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are omitted from the snapshot and listed with a reason in its ``unresolved_flags``.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is True. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Attempt immediate delivery of queued events, ended spans and autocaptured metrics, keeping the client reusable. For a client shared across requests or serverless invocations (including the module-level client), call ``flush()`` before a short-lived invocation returns. Use ``shutdown()`` instead only for final process cleanup or when disposing of a client that will not be reused. Flush does not stop the background workers or feature flag poller, and does not end open spans. Returning does not guarantee server receipt: pending work can remain after a timeout or span export failure, and failed events may be dropped by the consumers. Calls made directly from SDK callbacks such as ``on_error`` are deferred rather than blocking the worker that invoked the callback.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Seconds to wait for event queues to drain, shared across event lanes. Defaults to 10 seconds. Pass ``None`` to wait without a time limit; this does not guarantee successful delivery. Queued spans flush concurrently. The span exporter waits up to this many seconds for an in-flight flush, then uses a fresh drain budget once it acquires the lock. If the lock wait times out, the in-flight flush is left to finish. At least one span request is attempted after acquiring the lock, even with no budget left; retriable failures are retried after backoff while budget remains, with one last attempt at the deadline. Each span request is bounded by the client's ``timeout`` in seconds, and the last request is not cut short. This is therefore not a strict wall-clock limit for the whole call. With ``None``, a retriable span failure is left for a later flush rather than retried within this call.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name', distinct_id='user_id')\n# Before a serverless invocation returns; keep the shared client open.\nposthog.flush(timeout_seconds=10)" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nruntime = posthog.get_feature_flag_evaluation_runtime(\"my-flag\")\nif runtime is FeatureFlagEvaluationRuntime.SERVER:\n ..." - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate. A flag set to ``FeatureFlagEvaluationRuntime.ALL`` suits either runtime, so it is returned for ``CLIENT`` and for ``SERVER``, and asking for ``ALL`` returns every loaded flag. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "The runtime to match, as a ``FeatureFlagEvaluationRuntime`` or its string value.", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nclient_keys = posthog.get_feature_flag_keys_by_evaluation_runtime(\n FeatureFlagEvaluationRuntime.CLIENT\n)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user, preserving valid serialized JSON.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Optional[str]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team'). Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and end the consumer threads. Do not use directly, call `shutdown()` instead. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Attempt final delivery and permanently shut down the client. Call this for final process cleanup or when disposing of a client that will not be reused. It closes capture lanes, stops background workers and the feature flag poller, and tears down integrations. Do not call it at the end of each request or serverless invocation when the client is shared; call ``flush()`` before returning instead. A shut-down client cannot be reused; create a new client if needed. Normally this method blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Event draining has no timeout. Queued spans get one final flush with up to 30 seconds waiting for an in-flight flush, then a fresh 30-second drain budget; the last HTTP request is not cut short. Any spans it cannot send are discarded with a warning, as are spans still open. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. When called directly from an SDK callback such as ``on_error``, shutdown is deferred to avoid blocking the worker that invoked the callback. If the callback must coordinate a blocking shutdown, have it signal an application-owned thread and return before that thread calls shutdown. Do not wait inside the callback for another thread or task that calls a lifecycle method.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span. A forked child starts with no active span; pass the parent span to continue a trace across a fork.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog = Posthog(\"\", traces={\"service_name\": \"checkout-api\"})\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is delivered on an isolated queue with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name, normally one of the `$ai_*` event names. **kwargs: Same optional arguments as `capture()`.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import capture_ai\n\nuuid = capture_ai(\n \"$ai_generation\",\n distinct_id=\"user_123\",\n properties={\"$ai_model\": \"gpt-5\"},\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip. Overriding reserved exception properties through ``properties`` is deprecated and will stop working in the next major version.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation and omit flags that cannot be evaluated locally. The snapshot's ``unresolved_flags`` lists them with a reason.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is ``True``. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Attempt immediate delivery of queued events and ended spans, keeping the global client reusable. Call ``flush()`` before a short-lived request or serverless invocation returns when using the shared module-level client. Use ``shutdown()`` only for final process cleanup or a client that will not be reused. Flush does not stop the background workers or feature flag poller, and does not end open spans. Returning does not guarantee server receipt: pending work can remain after a timeout or span export failure, and failed events may be dropped by consumers. Calls made directly from SDK callbacks such as ``on_error`` are deferred rather than blocking the worker that invoked the callback.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Seconds to wait for event queues to drain, shared across event lanes. Defaults to 10 seconds. Pass ``None`` to wait without a time limit; this does not guarantee successful delivery. Queued spans flush concurrently, waiting up to this many seconds for an in-flight flush before starting a fresh drain budget. A lock wait timeout leaves the in-flight flush to finish. At least one span request is attempted after acquiring the lock, even with no budget left; retriable failures are retried after backoff while budget remains, with one last attempt at the deadline. The last span request is not cut short and is bounded by the client's ``timeout`` in seconds, so this is not a strict wall-clock limit for the whole call. With ``None``, a retriable span failure is left for a later flush rather than retried within this call.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "import posthog\nposthog.capture('event_name', distinct_id='user_id')\n# Before a serverless invocation returns; keep the global client open.\nposthog.flush(timeout_seconds=10)" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "Reads the `evaluation_runtime` each flag definition carries, so no extra request is made. Returns `None` when local evaluation has not loaded a definition for this key. A definition that carries no runtime reports `FeatureFlagEvaluationRuntime.ALL`, the default PostHog applies.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_evaluation_runtime\nruntime = get_feature_flag_evaluation_runtime(\"my-flag\")" - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate.", - "details": "A flag set to `FeatureFlagEvaluationRuntime.ALL` suits either runtime, so it is returned for `CLIENT` and for `SERVER`. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_keys_by_evaluation_runtime\nclient_keys = get_feature_flag_keys_by_evaluation_runtime(FeatureFlagEvaluationRuntime.CLIENT)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and stop the client's background workers. Use `shutdown()` directly in most cases. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Attempt final delivery and permanently shut down the global client. Call this for final process cleanup, not at the end of each request or serverless invocation that shares the module-level client. Use ``flush()`` before returning from those invocations instead. Shutdown closes capture lanes, stops background workers and the feature flag poller, and tears down integrations. The global client is not recreated automatically after shutdown. This normally blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Event draining has no timeout. Queued spans get a final flush with up to 30 seconds waiting for an in-flight flush, then a fresh 30-second drain budget; the last HTTP request is not cut short. Unsent queued spans and still-open spans are discarded with a warning. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. Calls made directly from SDK callbacks such as ``on_error`` are deferred to avoid deadlocking the worker. If blocking completion is required, signal an application-owned thread, return from the callback, and call ``shutdown()`` from that thread. Do not wait inside a callback for another thread or task calling a lifecycle method.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "import posthog\nposthog.traces = {\"service_name\": \"checkout-api\"}\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Tracing", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.84.2.json b/references/posthog-python-references-7.84.2.json deleted file mode 100644 index 26ee3007a..000000000 --- a/references/posthog-python-references-7.84.2.json +++ /dev/null @@ -1,3572 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.84.2", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "Optional[int]", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "Optional[int]", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "float" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "float" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "enable_full_ai_capture", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_trace_context", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "traces", - "description": "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.", - "isOptional": true, - "type": "dict" - }, - { - "name": "app_host", - "description": "Your PostHog app host, such as ``https://posthog.example.com``. ``emails`` sends there. Needed only when ``host`` is not PostHog Cloud, for example a reverse proxy, which must not receive the secret key.", - "isOptional": true, - "type": "str" - }, - { - "name": "email_request_timeout_seconds", - "description": "Timeout in seconds for each email send request. Defaults to 15.", - "isOptional": false, - "type": "float" - }, - { - "name": "email_request_max_retries", - "description": "Number of retries for an email send after a network error, a rate limit, or an unavailable service. Defaults to 2. Set to 0 when a job runner already retries the send.", - "isOptional": false, - "type": "int" - }, - { - "name": "migrated_from", - "description": "The email provider you moved from, such as ``\"resend\"``. ``emails`` sends it with every request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to. Falls back to the context distinct ID; the call is dropped with a warning if neither is available.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is queued on an isolated AI lane with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are omitted from the snapshot and listed with a reason in its ``unresolved_flags``.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is True. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Attempt immediate delivery of queued events, ended spans and autocaptured metrics, keeping the client reusable. For a client shared across requests or serverless invocations (including the module-level client), call ``flush()`` before a short-lived invocation returns. Use ``shutdown()`` instead only for final process cleanup or when disposing of a client that will not be reused. Flush does not stop the background workers or feature flag poller, and does not end open spans. Returning does not guarantee server receipt: pending work can remain after a timeout or span export failure, and failed events may be dropped by the consumers. Calls made directly from SDK callbacks such as ``on_error`` are deferred rather than blocking the worker that invoked the callback.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Seconds to wait for event queues to drain, shared across event lanes. Defaults to 10 seconds. Pass ``None`` to wait without a time limit; this does not guarantee successful delivery. Queued spans flush concurrently. The span exporter waits up to this many seconds for an in-flight flush, then uses a fresh drain budget once it acquires the lock. If the lock wait times out, the in-flight flush is left to finish. At least one span request is attempted after acquiring the lock, even with no budget left; retriable failures are retried after backoff while budget remains, with one last attempt at the deadline. Each span request is bounded by the client's ``timeout`` in seconds, and the last request is not cut short. This is therefore not a strict wall-clock limit for the whole call. With ``None``, a retriable span failure is left for a later flush rather than retried within this call.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name', distinct_id='user_id')\n# Before a serverless invocation returns; keep the shared client open.\nposthog.flush(timeout_seconds=10)" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nruntime = posthog.get_feature_flag_evaluation_runtime(\"my-flag\")\nif runtime is FeatureFlagEvaluationRuntime.SERVER:\n ..." - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate. A flag set to ``FeatureFlagEvaluationRuntime.ALL`` suits either runtime, so it is returned for ``CLIENT`` and for ``SERVER``, and asking for ``ALL`` returns every loaded flag. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "The runtime to match, as a ``FeatureFlagEvaluationRuntime`` or its string value.", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nclient_keys = posthog.get_feature_flag_keys_by_evaluation_runtime(\n FeatureFlagEvaluationRuntime.CLIENT\n)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user, preserving valid serialized JSON.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Optional[str]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team'). Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and end the consumer threads. Do not use directly, call `shutdown()` instead. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Attempt final delivery and permanently shut down the client. Call this for final process cleanup or when disposing of a client that will not be reused. It closes capture lanes, stops background workers and the feature flag poller, and tears down integrations. Do not call it at the end of each request or serverless invocation when the client is shared; call ``flush()`` before returning instead. A shut-down client cannot be reused; create a new client if needed. Normally this method blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Event draining has no timeout. Queued spans get one final flush with up to 30 seconds waiting for an in-flight flush, then a fresh 30-second drain budget; the last HTTP request is not cut short. Any spans it cannot send are discarded with a warning, as are spans still open. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. When called directly from an SDK callback such as ``on_error``, shutdown is deferred to avoid blocking the worker that invoked the callback. If the callback must coordinate a blocking shutdown, have it signal an application-owned thread and return before that thread calls shutdown. Do not wait inside the callback for another thread or task that calls a lifecycle method.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span. A forked child starts with no active span; pass the parent span to continue a trace across a fork.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog = Posthog(\"\", traces={\"service_name\": \"checkout-api\"})\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is delivered on an isolated queue with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name, normally one of the `$ai_*` event names. **kwargs: Same optional arguments as `capture()`.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import capture_ai\n\nuuid = capture_ai(\n \"$ai_generation\",\n distinct_id=\"user_123\",\n properties={\"$ai_model\": \"gpt-5\"},\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip. Overriding reserved exception properties through ``properties`` is deprecated and will stop working in the next major version.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation and omit flags that cannot be evaluated locally. The snapshot's ``unresolved_flags`` lists them with a reason.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is ``True``. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Attempt immediate delivery of queued events and ended spans, keeping the global client reusable. Call ``flush()`` before a short-lived request or serverless invocation returns when using the shared module-level client. Use ``shutdown()`` only for final process cleanup or a client that will not be reused. Flush does not stop the background workers or feature flag poller, and does not end open spans. Returning does not guarantee server receipt: pending work can remain after a timeout or span export failure, and failed events may be dropped by consumers. Calls made directly from SDK callbacks such as ``on_error`` are deferred rather than blocking the worker that invoked the callback.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Seconds to wait for event queues to drain, shared across event lanes. Defaults to 10 seconds. Pass ``None`` to wait without a time limit; this does not guarantee successful delivery. Queued spans flush concurrently, waiting up to this many seconds for an in-flight flush before starting a fresh drain budget. A lock wait timeout leaves the in-flight flush to finish. At least one span request is attempted after acquiring the lock, even with no budget left; retriable failures are retried after backoff while budget remains, with one last attempt at the deadline. The last span request is not cut short and is bounded by the client's ``timeout`` in seconds, so this is not a strict wall-clock limit for the whole call. With ``None``, a retriable span failure is left for a later flush rather than retried within this call.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "import posthog\nposthog.capture('event_name', distinct_id='user_id')\n# Before a serverless invocation returns; keep the global client open.\nposthog.flush(timeout_seconds=10)" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "Reads the `evaluation_runtime` each flag definition carries, so no extra request is made. Returns `None` when local evaluation has not loaded a definition for this key. A definition that carries no runtime reports `FeatureFlagEvaluationRuntime.ALL`, the default PostHog applies.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_evaluation_runtime\nruntime = get_feature_flag_evaluation_runtime(\"my-flag\")" - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate.", - "details": "A flag set to `FeatureFlagEvaluationRuntime.ALL` suits either runtime, so it is returned for `CLIENT` and for `SERVER`. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_keys_by_evaluation_runtime\nclient_keys = get_feature_flag_keys_by_evaluation_runtime(FeatureFlagEvaluationRuntime.CLIENT)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and stop the client's background workers. Use `shutdown()` directly in most cases. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Attempt final delivery and permanently shut down the global client. Call this for final process cleanup, not at the end of each request or serverless invocation that shares the module-level client. Use ``flush()`` before returning from those invocations instead. Shutdown closes capture lanes, stops background workers and the feature flag poller, and tears down integrations. The global client is not recreated automatically after shutdown. This normally blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Event draining has no timeout. Queued spans get a final flush with up to 30 seconds waiting for an in-flight flush, then a fresh 30-second drain budget; the last HTTP request is not cut short. Unsent queued spans and still-open spans are discarded with a warning. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. Calls made directly from SDK callbacks such as ``on_error`` are deferred to avoid deadlocking the worker. If blocking completion is required, signal an application-owned thread, return from the callback, and call ``shutdown()`` from that thread. Do not wait inside a callback for another thread or task calling a lifecycle method.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "import posthog\nposthog.traces = {\"service_name\": \"checkout-api\"}\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Tracing", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.85.0.json b/references/posthog-python-references-7.85.0.json deleted file mode 100644 index 8d26a3229..000000000 --- a/references/posthog-python-references-7.85.0.json +++ /dev/null @@ -1,3572 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.85.0", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "Optional[int]", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "Optional[int]", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "float" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "float" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "enable_full_ai_capture", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_trace_context", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "traces", - "description": "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.", - "isOptional": true, - "type": "dict" - }, - { - "name": "app_host", - "description": "Your PostHog app host, such as ``https://posthog.example.com``. ``emails`` sends there. Needed only when ``host`` is not PostHog Cloud, for example a reverse proxy, which must not receive the secret key.", - "isOptional": true, - "type": "str" - }, - { - "name": "email_request_timeout_seconds", - "description": "Timeout in seconds for each email send request. Defaults to 15.", - "isOptional": false, - "type": "float" - }, - { - "name": "email_request_max_retries", - "description": "Number of retries for an email send after a network error, a rate limit, or an unavailable service. Defaults to 2. Set to 0 when a job runner already retries the send.", - "isOptional": false, - "type": "int" - }, - { - "name": "migrated_from", - "description": "The email provider you moved from, such as ``\"resend\"``. ``emails`` sends it with every request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to. Falls back to the context distinct ID; the call is dropped with a warning if neither is available.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is queued on an isolated AI lane with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are omitted from the snapshot and listed with a reason in its ``unresolved_flags``.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is True. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Attempt immediate delivery of queued events, ended spans and autocaptured metrics, keeping the client reusable. For a client shared across requests or serverless invocations (including the module-level client), call ``flush()`` before a short-lived invocation returns. Use ``shutdown()`` instead only for final process cleanup or when disposing of a client that will not be reused. Flush does not stop the background workers or feature flag poller, and does not end open spans. Returning does not guarantee server receipt: pending work can remain after a timeout or span export failure, and failed events may be dropped by the consumers. Calls made directly from SDK callbacks such as ``on_error`` are deferred rather than blocking the worker that invoked the callback.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Seconds to wait for event queues to drain, shared across event lanes. Defaults to 10 seconds. Pass ``None`` to wait without a time limit; this does not guarantee successful delivery. Queued spans flush concurrently. The span exporter waits up to this many seconds for an in-flight flush, then uses a fresh drain budget once it acquires the lock. If the lock wait times out, the in-flight flush is left to finish. At least one span request is attempted after acquiring the lock, even with no budget left; retriable failures are retried after backoff while budget remains, with one last attempt at the deadline. Each span request is bounded by the client's ``timeout`` in seconds, and the last request is not cut short. This is therefore not a strict wall-clock limit for the whole call. With ``None``, a retriable span failure is left for a later flush rather than retried within this call.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name', distinct_id='user_id')\n# Before a serverless invocation returns; keep the shared client open.\nposthog.flush(timeout_seconds=10)" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nruntime = posthog.get_feature_flag_evaluation_runtime(\"my-flag\")\nif runtime is FeatureFlagEvaluationRuntime.SERVER:\n ..." - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate. A flag set to ``FeatureFlagEvaluationRuntime.ALL`` suits either runtime, so it is returned for ``CLIENT`` and for ``SERVER``, and asking for ``ALL`` returns every loaded flag. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "The runtime to match, as a ``FeatureFlagEvaluationRuntime`` or its string value.", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nclient_keys = posthog.get_feature_flag_keys_by_evaluation_runtime(\n FeatureFlagEvaluationRuntime.CLIENT\n)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user, preserving valid serialized JSON.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Optional[str]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team'). Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and end the consumer threads. Do not use directly, call `shutdown()` instead. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Attempt final delivery and permanently shut down the client. Call this for final process cleanup or when disposing of a client that will not be reused. It closes capture lanes, stops background workers and the feature flag poller, and tears down integrations. Do not call it at the end of each request or serverless invocation when the client is shared; call ``flush()`` before returning instead. A shut-down client cannot be reused; create a new client if needed. Normally this method blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Event draining has no timeout. Queued spans get one final flush with up to 30 seconds waiting for an in-flight flush, then a fresh 30-second drain budget; the last HTTP request is not cut short. Any spans it cannot send are discarded with a warning, as are spans still open. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. When called directly from an SDK callback such as ``on_error``, shutdown is deferred to avoid blocking the worker that invoked the callback. If the callback must coordinate a blocking shutdown, have it signal an application-owned thread and return before that thread calls shutdown. Do not wait inside the callback for another thread or task that calls a lifecycle method.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span. A forked child starts with no active span; pass the parent span to continue a trace across a fork.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog = Posthog(\"\", traces={\"service_name\": \"checkout-api\"})\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is delivered on an isolated queue with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name, normally one of the `$ai_*` event names. **kwargs: Same optional arguments as `capture()`.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import capture_ai\n\nuuid = capture_ai(\n \"$ai_generation\",\n distinct_id=\"user_123\",\n properties={\"$ai_model\": \"gpt-5\"},\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip. Overriding reserved exception properties through ``properties`` is deprecated and will stop working in the next major version.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation and omit flags that cannot be evaluated locally. The snapshot's ``unresolved_flags`` lists them with a reason.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is ``True``. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Attempt immediate delivery of queued events and ended spans, keeping the global client reusable. Call ``flush()`` before a short-lived request or serverless invocation returns when using the shared module-level client. Use ``shutdown()`` only for final process cleanup or a client that will not be reused. Flush does not stop the background workers or feature flag poller, and does not end open spans. Returning does not guarantee server receipt: pending work can remain after a timeout or span export failure, and failed events may be dropped by consumers. Calls made directly from SDK callbacks such as ``on_error`` are deferred rather than blocking the worker that invoked the callback.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Seconds to wait for event queues to drain, shared across event lanes. Defaults to 10 seconds. Pass ``None`` to wait without a time limit; this does not guarantee successful delivery. Queued spans flush concurrently, waiting up to this many seconds for an in-flight flush before starting a fresh drain budget. A lock wait timeout leaves the in-flight flush to finish. At least one span request is attempted after acquiring the lock, even with no budget left; retriable failures are retried after backoff while budget remains, with one last attempt at the deadline. The last span request is not cut short and is bounded by the client's ``timeout`` in seconds, so this is not a strict wall-clock limit for the whole call. With ``None``, a retriable span failure is left for a later flush rather than retried within this call.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "import posthog\nposthog.capture('event_name', distinct_id='user_id')\n# Before a serverless invocation returns; keep the global client open.\nposthog.flush(timeout_seconds=10)" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "Reads the `evaluation_runtime` each flag definition carries, so no extra request is made. Returns `None` when local evaluation has not loaded a definition for this key. A definition that carries no runtime reports `FeatureFlagEvaluationRuntime.ALL`, the default PostHog applies.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_evaluation_runtime\nruntime = get_feature_flag_evaluation_runtime(\"my-flag\")" - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate.", - "details": "A flag set to `FeatureFlagEvaluationRuntime.ALL` suits either runtime, so it is returned for `CLIENT` and for `SERVER`. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_keys_by_evaluation_runtime\nclient_keys = get_feature_flag_keys_by_evaluation_runtime(FeatureFlagEvaluationRuntime.CLIENT)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and stop the client's background workers. Use `shutdown()` directly in most cases. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Attempt final delivery and permanently shut down the global client. Call this for final process cleanup, not at the end of each request or serverless invocation that shares the module-level client. Use ``flush()`` before returning from those invocations instead. Shutdown closes capture lanes, stops background workers and the feature flag poller, and tears down integrations. The global client is not recreated automatically after shutdown. This normally blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Event draining has no timeout. Queued spans get a final flush with up to 30 seconds waiting for an in-flight flush, then a fresh 30-second drain budget; the last HTTP request is not cut short. Unsent queued spans and still-open spans are discarded with a warning. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. Calls made directly from SDK callbacks such as ``on_error`` are deferred to avoid deadlocking the worker. If blocking completion is required, signal an application-owned thread, return from the callback, and call ``shutdown()`` from that thread. Do not wait inside a callback for another thread or task calling a lifecycle method.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "import posthog\nposthog.traces = {\"service_name\": \"checkout-api\"}\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Tracing", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.86.0.json b/references/posthog-python-references-7.86.0.json deleted file mode 100644 index 7b9ca3f88..000000000 --- a/references/posthog-python-references-7.86.0.json +++ /dev/null @@ -1,3572 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.86.0", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "Optional[int]", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "Optional[int]", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "float" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "float" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "enable_full_ai_capture", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_trace_context", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "traces", - "description": "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.", - "isOptional": true, - "type": "dict" - }, - { - "name": "app_host", - "description": "Your PostHog app host, such as ``https://posthog.example.com``. ``emails`` sends there. Needed only when ``host`` is not PostHog Cloud, for example a reverse proxy, which must not receive the secret key.", - "isOptional": true, - "type": "str" - }, - { - "name": "email_request_timeout_seconds", - "description": "Timeout in seconds for each email send request. Defaults to 15.", - "isOptional": false, - "type": "float" - }, - { - "name": "email_request_max_retries", - "description": "Number of retries for an email send after a network error, a rate limit, or an unavailable service. Defaults to 2. Set to 0 when a job runner already retries the send.", - "isOptional": false, - "type": "int" - }, - { - "name": "migrated_from", - "description": "The email provider you moved from, such as ``\"resend\"``. ``emails`` sends it with every request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to. Falls back to the context distinct ID; the call is dropped with a warning if neither is available.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is queued on an isolated AI lane with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are omitted from the snapshot and listed with a reason in its ``unresolved_flags``.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is True. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Attempt immediate delivery of queued events, ended spans and autocaptured metrics, keeping the client reusable. For a client shared across requests or serverless invocations (including the module-level client), call ``flush()`` before a short-lived invocation returns. Use ``shutdown()`` instead only for final process cleanup or when disposing of a client that will not be reused. Flush does not stop the background workers or feature flag poller, and does not end open spans. Returning does not guarantee server receipt: pending work can remain after a timeout or span export failure, and failed events may be dropped by the consumers. Calls made directly from SDK callbacks such as ``on_error`` are deferred rather than blocking the worker that invoked the callback.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Seconds to wait for event queues to drain, shared across event lanes. Defaults to 10 seconds. Pass ``None`` to wait without a time limit; this does not guarantee successful delivery. Queued spans flush concurrently. The span exporter waits up to this many seconds for an in-flight flush, then uses a fresh drain budget once it acquires the lock. If the lock wait times out, the in-flight flush is left to finish. At least one span request is attempted after acquiring the lock, even with no budget left; retriable failures are retried after backoff while budget remains, with one last attempt at the deadline. Each span request is bounded by the client's ``timeout`` in seconds, and the last request is not cut short. This is therefore not a strict wall-clock limit for the whole call. With ``None``, a retriable span failure is left for a later flush rather than retried within this call.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name', distinct_id='user_id')\n# Before a serverless invocation returns; keep the shared client open.\nposthog.flush(timeout_seconds=10)" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nruntime = posthog.get_feature_flag_evaluation_runtime(\"my-flag\")\nif runtime is FeatureFlagEvaluationRuntime.SERVER:\n ..." - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate. A flag set to ``FeatureFlagEvaluationRuntime.ALL`` suits either runtime, so it is returned for ``CLIENT`` and for ``SERVER``, and asking for ``ALL`` returns every loaded flag. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "The runtime to match, as a ``FeatureFlagEvaluationRuntime`` or its string value.", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nclient_keys = posthog.get_feature_flag_keys_by_evaluation_runtime(\n FeatureFlagEvaluationRuntime.CLIENT\n)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user, preserving valid serialized JSON.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Optional[str]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team'). Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and end the consumer threads. Do not use directly, call `shutdown()` instead. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Attempt final delivery and permanently shut down the client. Call this for final process cleanup or when disposing of a client that will not be reused. It closes capture lanes, stops background workers and the feature flag poller, and tears down integrations. Do not call it at the end of each request or serverless invocation when the client is shared; call ``flush()`` before returning instead. A shut-down client cannot be reused; create a new client if needed. Normally this method blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Event draining has no timeout. Queued spans get one final flush with up to 30 seconds waiting for an in-flight flush, then a fresh 30-second drain budget; the last HTTP request is not cut short. Any spans it cannot send are discarded with a warning, as are spans still open. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. When called directly from an SDK callback such as ``on_error``, shutdown is deferred to avoid blocking the worker that invoked the callback. If the callback must coordinate a blocking shutdown, have it signal an application-owned thread and return before that thread calls shutdown. Do not wait inside the callback for another thread or task that calls a lifecycle method.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span. A forked child starts with no active span; pass the parent span to continue a trace across a fork.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog = Posthog(\"\", traces={\"service_name\": \"checkout-api\"})\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is delivered on an isolated queue with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name, normally one of the `$ai_*` event names. **kwargs: Same optional arguments as `capture()`.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import capture_ai\n\nuuid = capture_ai(\n \"$ai_generation\",\n distinct_id=\"user_123\",\n properties={\"$ai_model\": \"gpt-5\"},\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip. Overriding reserved exception properties through ``properties`` is deprecated and will stop working in the next major version.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation and omit flags that cannot be evaluated locally. The snapshot's ``unresolved_flags`` lists them with a reason.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is ``True``. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Attempt immediate delivery of queued events and ended spans, keeping the global client reusable. Call ``flush()`` before a short-lived request or serverless invocation returns when using the shared module-level client. Use ``shutdown()`` only for final process cleanup or a client that will not be reused. Flush does not stop the background workers or feature flag poller, and does not end open spans. Returning does not guarantee server receipt: pending work can remain after a timeout or span export failure, and failed events may be dropped by consumers. Calls made directly from SDK callbacks such as ``on_error`` are deferred rather than blocking the worker that invoked the callback.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Seconds to wait for event queues to drain, shared across event lanes. Defaults to 10 seconds. Pass ``None`` to wait without a time limit; this does not guarantee successful delivery. Queued spans flush concurrently, waiting up to this many seconds for an in-flight flush before starting a fresh drain budget. A lock wait timeout leaves the in-flight flush to finish. At least one span request is attempted after acquiring the lock, even with no budget left; retriable failures are retried after backoff while budget remains, with one last attempt at the deadline. The last span request is not cut short and is bounded by the client's ``timeout`` in seconds, so this is not a strict wall-clock limit for the whole call. With ``None``, a retriable span failure is left for a later flush rather than retried within this call.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "import posthog\nposthog.capture('event_name', distinct_id='user_id')\n# Before a serverless invocation returns; keep the global client open.\nposthog.flush(timeout_seconds=10)" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "Reads the `evaluation_runtime` each flag definition carries, so no extra request is made. Returns `None` when local evaluation has not loaded a definition for this key. A definition that carries no runtime reports `FeatureFlagEvaluationRuntime.ALL`, the default PostHog applies.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_evaluation_runtime\nruntime = get_feature_flag_evaluation_runtime(\"my-flag\")" - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate.", - "details": "A flag set to `FeatureFlagEvaluationRuntime.ALL` suits either runtime, so it is returned for `CLIENT` and for `SERVER`. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_keys_by_evaluation_runtime\nclient_keys = get_feature_flag_keys_by_evaluation_runtime(FeatureFlagEvaluationRuntime.CLIENT)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and stop the client's background workers. Use `shutdown()` directly in most cases. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Attempt final delivery and permanently shut down the global client. Call this for final process cleanup, not at the end of each request or serverless invocation that shares the module-level client. Use ``flush()`` before returning from those invocations instead. Shutdown closes capture lanes, stops background workers and the feature flag poller, and tears down integrations. The global client is not recreated automatically after shutdown. This normally blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Event draining has no timeout. Queued spans get a final flush with up to 30 seconds waiting for an in-flight flush, then a fresh 30-second drain budget; the last HTTP request is not cut short. Unsent queued spans and still-open spans are discarded with a warning. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. Calls made directly from SDK callbacks such as ``on_error`` are deferred to avoid deadlocking the worker. If blocking completion is required, signal an application-owned thread, return from the callback, and call ``shutdown()`` from that thread. Do not wait inside a callback for another thread or task calling a lifecycle method.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "import posthog\nposthog.traces = {\"service_name\": \"checkout-api\"}\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Tracing", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.86.1.json b/references/posthog-python-references-7.86.1.json deleted file mode 100644 index 687877368..000000000 --- a/references/posthog-python-references-7.86.1.json +++ /dev/null @@ -1,3572 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.86.1", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "Optional[int]", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "Optional[int]", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "float" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "float" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "enable_full_ai_capture", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_trace_context", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "traces", - "description": "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.", - "isOptional": true, - "type": "dict" - }, - { - "name": "app_host", - "description": "Your PostHog app host, such as ``https://posthog.example.com``. ``emails`` sends there. Needed only when ``host`` is not PostHog Cloud, for example a reverse proxy, which must not receive the secret key.", - "isOptional": true, - "type": "str" - }, - { - "name": "email_request_timeout_seconds", - "description": "Timeout in seconds for each email send request. Defaults to 15.", - "isOptional": false, - "type": "float" - }, - { - "name": "email_request_max_retries", - "description": "Number of retries for an email send after a network error, a rate limit, or an unavailable service. Defaults to 2. Set to 0 when a job runner already retries the send.", - "isOptional": false, - "type": "int" - }, - { - "name": "migrated_from", - "description": "The email provider you moved from, such as ``\"resend\"``. ``emails`` sends it with every request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to. Falls back to the context distinct ID; the call is dropped with a warning if neither is available.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is queued on an isolated AI lane with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are omitted from the snapshot and listed with a reason in its ``unresolved_flags``.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is True. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Attempt immediate delivery of queued events, ended spans and autocaptured metrics, keeping the client reusable. For a client shared across requests or serverless invocations (including the module-level client), call ``flush()`` before a short-lived invocation returns. Use ``shutdown()`` instead only for final process cleanup or when disposing of a client that will not be reused. Flush does not stop the background workers or feature flag poller, and does not end open spans. Returning does not guarantee server receipt: pending work can remain after a timeout or span export failure, and failed events may be dropped by the consumers. Calls made directly from SDK callbacks such as ``on_error`` are deferred rather than blocking the worker that invoked the callback.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Seconds to wait for event queues to drain, shared across event lanes. Defaults to 10 seconds. Pass ``None`` to wait without a time limit; this does not guarantee successful delivery. Queued spans flush concurrently. The span exporter waits up to this many seconds for an in-flight flush, then uses a fresh drain budget once it acquires the lock. If the lock wait times out, the in-flight flush is left to finish. At least one span request is attempted after acquiring the lock, even with no budget left; retriable failures are retried after backoff while budget remains, with one last attempt at the deadline. Each span request is bounded by the client's ``timeout`` in seconds, and the last request is not cut short. This is therefore not a strict wall-clock limit for the whole call. With ``None``, a retriable span failure is left for a later flush rather than retried within this call.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name', distinct_id='user_id')\n# Before a serverless invocation returns; keep the shared client open.\nposthog.flush(timeout_seconds=10)" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nruntime = posthog.get_feature_flag_evaluation_runtime(\"my-flag\")\nif runtime is FeatureFlagEvaluationRuntime.SERVER:\n ..." - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate. A flag set to ``FeatureFlagEvaluationRuntime.ALL`` suits either runtime, so it is returned for ``CLIENT`` and for ``SERVER``, and asking for ``ALL`` returns every loaded flag. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "The runtime to match, as a ``FeatureFlagEvaluationRuntime`` or its string value.", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nclient_keys = posthog.get_feature_flag_keys_by_evaluation_runtime(\n FeatureFlagEvaluationRuntime.CLIENT\n)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user, preserving valid serialized JSON.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Optional[str]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team'). Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and end the consumer threads. Do not use directly, call `shutdown()` instead. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Attempt final delivery and permanently shut down the client. Call this for final process cleanup or when disposing of a client that will not be reused. It closes capture lanes, stops background workers and the feature flag poller, and tears down integrations. Do not call it at the end of each request or serverless invocation when the client is shared; call ``flush()`` before returning instead. A shut-down client cannot be reused; create a new client if needed. Normally this method blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Event draining has no timeout. Queued spans get one final flush with up to 30 seconds waiting for an in-flight flush, then a fresh 30-second drain budget; the last HTTP request is not cut short. Any spans it cannot send are discarded with a warning, as are spans still open. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. When called directly from an SDK callback such as ``on_error``, shutdown is deferred to avoid blocking the worker that invoked the callback. If the callback must coordinate a blocking shutdown, have it signal an application-owned thread and return before that thread calls shutdown. Do not wait inside the callback for another thread or task that calls a lifecycle method.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span. A forked child starts with no active span; pass the parent span to continue a trace across a fork.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog = Posthog(\"\", traces={\"service_name\": \"checkout-api\"})\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is delivered on an isolated queue with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name, normally one of the `$ai_*` event names. **kwargs: Same optional arguments as `capture()`.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import capture_ai\n\nuuid = capture_ai(\n \"$ai_generation\",\n distinct_id=\"user_123\",\n properties={\"$ai_model\": \"gpt-5\"},\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip. Overriding reserved exception properties through ``properties`` is deprecated and will stop working in the next major version.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation and omit flags that cannot be evaluated locally. The snapshot's ``unresolved_flags`` lists them with a reason.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is ``True``. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Attempt immediate delivery of queued events and ended spans, keeping the global client reusable. Call ``flush()`` before a short-lived request or serverless invocation returns when using the shared module-level client. Use ``shutdown()`` only for final process cleanup or a client that will not be reused. Flush does not stop the background workers or feature flag poller, and does not end open spans. Returning does not guarantee server receipt: pending work can remain after a timeout or span export failure, and failed events may be dropped by consumers. Calls made directly from SDK callbacks such as ``on_error`` are deferred rather than blocking the worker that invoked the callback.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Seconds to wait for event queues to drain, shared across event lanes. Defaults to 10 seconds. Pass ``None`` to wait without a time limit; this does not guarantee successful delivery. Queued spans flush concurrently, waiting up to this many seconds for an in-flight flush before starting a fresh drain budget. A lock wait timeout leaves the in-flight flush to finish. At least one span request is attempted after acquiring the lock, even with no budget left; retriable failures are retried after backoff while budget remains, with one last attempt at the deadline. The last span request is not cut short and is bounded by the client's ``timeout`` in seconds, so this is not a strict wall-clock limit for the whole call. With ``None``, a retriable span failure is left for a later flush rather than retried within this call.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "import posthog\nposthog.capture('event_name', distinct_id='user_id')\n# Before a serverless invocation returns; keep the global client open.\nposthog.flush(timeout_seconds=10)" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "Reads the `evaluation_runtime` each flag definition carries, so no extra request is made. Returns `None` when local evaluation has not loaded a definition for this key. A definition that carries no runtime reports `FeatureFlagEvaluationRuntime.ALL`, the default PostHog applies.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_evaluation_runtime\nruntime = get_feature_flag_evaluation_runtime(\"my-flag\")" - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate.", - "details": "A flag set to `FeatureFlagEvaluationRuntime.ALL` suits either runtime, so it is returned for `CLIENT` and for `SERVER`. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_keys_by_evaluation_runtime\nclient_keys = get_feature_flag_keys_by_evaluation_runtime(FeatureFlagEvaluationRuntime.CLIENT)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and stop the client's background workers. Use `shutdown()` directly in most cases. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Attempt final delivery and permanently shut down the global client. Call this for final process cleanup, not at the end of each request or serverless invocation that shares the module-level client. Use ``flush()`` before returning from those invocations instead. Shutdown closes capture lanes, stops background workers and the feature flag poller, and tears down integrations. The global client is not recreated automatically after shutdown. This normally blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Event draining has no timeout. Queued spans get a final flush with up to 30 seconds waiting for an in-flight flush, then a fresh 30-second drain budget; the last HTTP request is not cut short. Unsent queued spans and still-open spans are discarded with a warning. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. Calls made directly from SDK callbacks such as ``on_error`` are deferred to avoid deadlocking the worker. If blocking completion is required, signal an application-owned thread, return from the callback, and call ``shutdown()`` from that thread. Do not wait inside a callback for another thread or task calling a lifecycle method.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "import posthog\nposthog.traces = {\"service_name\": \"checkout-api\"}\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Tracing", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.86.2.json b/references/posthog-python-references-7.86.2.json deleted file mode 100644 index 3caf38994..000000000 --- a/references/posthog-python-references-7.86.2.json +++ /dev/null @@ -1,3572 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.86.2", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "Optional[int]", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "Optional[int]", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "float" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "float" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "enable_full_ai_capture", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_trace_context", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "traces", - "description": "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.", - "isOptional": true, - "type": "dict" - }, - { - "name": "app_host", - "description": "Your PostHog app host, such as ``https://posthog.example.com``. ``emails`` sends there. Needed only when ``host`` is not PostHog Cloud, for example a reverse proxy, which must not receive the secret key.", - "isOptional": true, - "type": "str" - }, - { - "name": "email_request_timeout_seconds", - "description": "Timeout in seconds for each email send request. Defaults to 15.", - "isOptional": false, - "type": "float" - }, - { - "name": "email_request_max_retries", - "description": "Number of retries for an email send after a network error, a rate limit, or an unavailable service. Defaults to 2. Set to 0 when a job runner already retries the send.", - "isOptional": false, - "type": "int" - }, - { - "name": "migrated_from", - "description": "The email provider you moved from, such as ``\"resend\"``. ``emails`` sends it with every request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to. Falls back to the context distinct ID; the call is dropped with a warning if neither is available.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is queued on an isolated AI lane with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are omitted from the snapshot and listed with a reason in its ``unresolved_flags``.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is True. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Attempt immediate delivery of queued events, ended spans and autocaptured metrics, keeping the client reusable. For a client shared across requests or serverless invocations (including the module-level client), call ``flush()`` before a short-lived invocation returns. Use ``shutdown()`` instead only for final process cleanup or when disposing of a client that will not be reused. Flush does not stop the background workers or feature flag poller, and does not end open spans. Returning does not guarantee server receipt: pending work can remain after a timeout or span export failure, and failed events may be dropped by the consumers. Calls made directly from SDK callbacks such as ``on_error`` are deferred rather than blocking the worker that invoked the callback.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Seconds to wait for event queues to drain, shared across event lanes. Defaults to 10 seconds. Pass ``None`` to wait without a time limit; this does not guarantee successful delivery. Queued spans flush concurrently. The span exporter waits up to this many seconds for an in-flight flush, then uses a fresh drain budget once it acquires the lock. If the lock wait times out, the in-flight flush is left to finish. At least one span request is attempted after acquiring the lock, even with no budget left; retriable failures are retried after backoff while budget remains, with one last attempt at the deadline. Each span request is bounded by the client's ``timeout`` in seconds, and the last request is not cut short. This is therefore not a strict wall-clock limit for the whole call. With ``None``, a retriable span failure is left for a later flush rather than retried within this call.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name', distinct_id='user_id')\n# Before a serverless invocation returns; keep the shared client open.\nposthog.flush(timeout_seconds=10)" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nruntime = posthog.get_feature_flag_evaluation_runtime(\"my-flag\")\nif runtime is FeatureFlagEvaluationRuntime.SERVER:\n ..." - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate. A flag set to ``FeatureFlagEvaluationRuntime.ALL`` suits either runtime, so it is returned for ``CLIENT`` and for ``SERVER``, and asking for ``ALL`` returns every loaded flag. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "The runtime to match, as a ``FeatureFlagEvaluationRuntime`` or its string value.", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nclient_keys = posthog.get_feature_flag_keys_by_evaluation_runtime(\n FeatureFlagEvaluationRuntime.CLIENT\n)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user, preserving valid serialized JSON.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Optional[str]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team'). Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and end the consumer threads. Do not use directly, call `shutdown()` instead. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Attempt final delivery and permanently shut down the client. Call this for final process cleanup or when disposing of a client that will not be reused. It closes capture lanes, stops background workers and the feature flag poller, and tears down integrations. Do not call it at the end of each request or serverless invocation when the client is shared; call ``flush()`` before returning instead. A shut-down client cannot be reused; create a new client if needed. Normally this method blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Event draining has no timeout. Queued spans get one final flush with up to 30 seconds waiting for an in-flight flush, then a fresh 30-second drain budget; the last HTTP request is not cut short. Any spans it cannot send are discarded with a warning, as are spans still open. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. When called directly from an SDK callback such as ``on_error``, shutdown is deferred to avoid blocking the worker that invoked the callback. If the callback must coordinate a blocking shutdown, have it signal an application-owned thread and return before that thread calls shutdown. Do not wait inside the callback for another thread or task that calls a lifecycle method.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span. A forked child starts with no active span; pass the parent span to continue a trace across a fork.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog = Posthog(\"\", traces={\"service_name\": \"checkout-api\"})\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is delivered on an isolated queue with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name, normally one of the `$ai_*` event names. **kwargs: Same optional arguments as `capture()`.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import capture_ai\n\nuuid = capture_ai(\n \"$ai_generation\",\n distinct_id=\"user_123\",\n properties={\"$ai_model\": \"gpt-5\"},\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip. Overriding reserved exception properties through ``properties`` is deprecated and will stop working in the next major version.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation and omit flags that cannot be evaluated locally. The snapshot's ``unresolved_flags`` lists them with a reason.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is ``True``. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Attempt immediate delivery of queued events and ended spans, keeping the global client reusable. Call ``flush()`` before a short-lived request or serverless invocation returns when using the shared module-level client. Use ``shutdown()`` only for final process cleanup or a client that will not be reused. Flush does not stop the background workers or feature flag poller, and does not end open spans. Returning does not guarantee server receipt: pending work can remain after a timeout or span export failure, and failed events may be dropped by consumers. Calls made directly from SDK callbacks such as ``on_error`` are deferred rather than blocking the worker that invoked the callback.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Seconds to wait for event queues to drain, shared across event lanes. Defaults to 10 seconds. Pass ``None`` to wait without a time limit; this does not guarantee successful delivery. Queued spans flush concurrently, waiting up to this many seconds for an in-flight flush before starting a fresh drain budget. A lock wait timeout leaves the in-flight flush to finish. At least one span request is attempted after acquiring the lock, even with no budget left; retriable failures are retried after backoff while budget remains, with one last attempt at the deadline. The last span request is not cut short and is bounded by the client's ``timeout`` in seconds, so this is not a strict wall-clock limit for the whole call. With ``None``, a retriable span failure is left for a later flush rather than retried within this call.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "import posthog\nposthog.capture('event_name', distinct_id='user_id')\n# Before a serverless invocation returns; keep the global client open.\nposthog.flush(timeout_seconds=10)" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "Reads the `evaluation_runtime` each flag definition carries, so no extra request is made. Returns `None` when local evaluation has not loaded a definition for this key. A definition that carries no runtime reports `FeatureFlagEvaluationRuntime.ALL`, the default PostHog applies.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_evaluation_runtime\nruntime = get_feature_flag_evaluation_runtime(\"my-flag\")" - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate.", - "details": "A flag set to `FeatureFlagEvaluationRuntime.ALL` suits either runtime, so it is returned for `CLIENT` and for `SERVER`. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_keys_by_evaluation_runtime\nclient_keys = get_feature_flag_keys_by_evaluation_runtime(FeatureFlagEvaluationRuntime.CLIENT)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and stop the client's background workers. Use `shutdown()` directly in most cases. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Attempt final delivery and permanently shut down the global client. Call this for final process cleanup, not at the end of each request or serverless invocation that shares the module-level client. Use ``flush()`` before returning from those invocations instead. Shutdown closes capture lanes, stops background workers and the feature flag poller, and tears down integrations. The global client is not recreated automatically after shutdown. This normally blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Event draining has no timeout. Queued spans get a final flush with up to 30 seconds waiting for an in-flight flush, then a fresh 30-second drain budget; the last HTTP request is not cut short. Unsent queued spans and still-open spans are discarded with a warning. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. Calls made directly from SDK callbacks such as ``on_error`` are deferred to avoid deadlocking the worker. If blocking completion is required, signal an application-owned thread, return from the callback, and call ``shutdown()`` from that thread. Do not wait inside a callback for another thread or task calling a lifecycle method.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "import posthog\nposthog.traces = {\"service_name\": \"checkout-api\"}\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Tracing", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.86.3.json b/references/posthog-python-references-7.86.3.json deleted file mode 100644 index 2ed52742a..000000000 --- a/references/posthog-python-references-7.86.3.json +++ /dev/null @@ -1,3572 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.86.3", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "Optional[int]", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "Optional[int]", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "float" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "float" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "enable_full_ai_capture", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_trace_context", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "traces", - "description": "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.", - "isOptional": true, - "type": "dict" - }, - { - "name": "app_host", - "description": "Your PostHog app host, such as ``https://posthog.example.com``. ``emails`` sends there. Needed only when ``host`` is not PostHog Cloud, for example a reverse proxy, which must not receive the secret key.", - "isOptional": true, - "type": "str" - }, - { - "name": "email_request_timeout_seconds", - "description": "Timeout in seconds for each email send request. Defaults to 15.", - "isOptional": false, - "type": "float" - }, - { - "name": "email_request_max_retries", - "description": "Number of retries for an email send after a network error, a rate limit, or an unavailable service. Defaults to 2. Set to 0 when a job runner already retries the send.", - "isOptional": false, - "type": "int" - }, - { - "name": "migrated_from", - "description": "The email provider you moved from, such as ``\"resend\"``. ``emails`` sends it with every request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to. Falls back to the context distinct ID; the call is dropped with a warning if neither is available.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is queued on an isolated AI lane with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are omitted from the snapshot and listed with a reason in its ``unresolved_flags``.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is True. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Attempt immediate delivery of queued events, ended spans and autocaptured metrics, keeping the client reusable. For a client shared across requests or serverless invocations (including the module-level client), call ``flush()`` before a short-lived invocation returns. Use ``shutdown()`` instead only for final process cleanup or when disposing of a client that will not be reused. Flush does not stop the background workers or feature flag poller, and does not end open spans. Returning does not guarantee server receipt: pending work can remain after a timeout or span export failure, and failed events may be dropped by the consumers. Calls made directly from SDK callbacks such as ``on_error`` are deferred rather than blocking the worker that invoked the callback.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Seconds to wait for event queues to drain, shared across event lanes. Defaults to 10 seconds. Pass ``None`` to wait without a time limit; this does not guarantee successful delivery. Queued spans flush concurrently. The span exporter waits up to this many seconds for an in-flight flush, then uses a fresh drain budget once it acquires the lock. If the lock wait times out, the in-flight flush is left to finish. At least one span request is attempted after acquiring the lock, even with no budget left; retriable failures are retried after backoff while budget remains, with one last attempt at the deadline. Each span request is bounded by the client's ``timeout`` in seconds, and the last request is not cut short. This is therefore not a strict wall-clock limit for the whole call. With ``None``, a retriable span failure is left for a later flush rather than retried within this call.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name', distinct_id='user_id')\n# Before a serverless invocation returns; keep the shared client open.\nposthog.flush(timeout_seconds=10)" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nruntime = posthog.get_feature_flag_evaluation_runtime(\"my-flag\")\nif runtime is FeatureFlagEvaluationRuntime.SERVER:\n ..." - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate. A flag set to ``FeatureFlagEvaluationRuntime.ALL`` suits either runtime, so it is returned for ``CLIENT`` and for ``SERVER``, and asking for ``ALL`` returns every loaded flag. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "The runtime to match, as a ``FeatureFlagEvaluationRuntime`` or its string value.", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nclient_keys = posthog.get_feature_flag_keys_by_evaluation_runtime(\n FeatureFlagEvaluationRuntime.CLIENT\n)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user, preserving valid serialized JSON.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Optional[str]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team'). Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and end the consumer threads. Do not use directly, call `shutdown()` instead. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Attempt final delivery and permanently shut down the client. Call this for final process cleanup or when disposing of a client that will not be reused. It closes capture lanes, stops background workers and the feature flag poller, and tears down integrations. Do not call it at the end of each request or serverless invocation when the client is shared; call ``flush()`` before returning instead. A shut-down client cannot be reused; create a new client if needed. Normally this method blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Event draining has no timeout. Queued spans get one final flush with up to 30 seconds waiting for an in-flight flush, then a fresh 30-second drain budget; the last HTTP request is not cut short. Any spans it cannot send are discarded with a warning, as are spans still open. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. When called directly from an SDK callback such as ``on_error``, shutdown is deferred to avoid blocking the worker that invoked the callback. If the callback must coordinate a blocking shutdown, have it signal an application-owned thread and return before that thread calls shutdown. Do not wait inside the callback for another thread or task that calls a lifecycle method.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span. A forked child starts with no active span; pass the parent span to continue a trace across a fork.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog = Posthog(\"\", traces={\"service_name\": \"checkout-api\"})\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is delivered on an isolated queue with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name, normally one of the `$ai_*` event names. **kwargs: Same optional arguments as `capture()`.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import capture_ai\n\nuuid = capture_ai(\n \"$ai_generation\",\n distinct_id=\"user_123\",\n properties={\"$ai_model\": \"gpt-5\"},\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip. Overriding reserved exception properties through ``properties`` is deprecated and will stop working in the next major version.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation and omit flags that cannot be evaluated locally. The snapshot's ``unresolved_flags`` lists them with a reason.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is ``True``. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Attempt immediate delivery of queued events and ended spans, keeping the global client reusable. Call ``flush()`` before a short-lived request or serverless invocation returns when using the shared module-level client. Use ``shutdown()`` only for final process cleanup or a client that will not be reused. Flush does not stop the background workers or feature flag poller, and does not end open spans. Returning does not guarantee server receipt: pending work can remain after a timeout or span export failure, and failed events may be dropped by consumers. Calls made directly from SDK callbacks such as ``on_error`` are deferred rather than blocking the worker that invoked the callback.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Seconds to wait for event queues to drain, shared across event lanes. Defaults to 10 seconds. Pass ``None`` to wait without a time limit; this does not guarantee successful delivery. Queued spans flush concurrently, waiting up to this many seconds for an in-flight flush before starting a fresh drain budget. A lock wait timeout leaves the in-flight flush to finish. At least one span request is attempted after acquiring the lock, even with no budget left; retriable failures are retried after backoff while budget remains, with one last attempt at the deadline. The last span request is not cut short and is bounded by the client's ``timeout`` in seconds, so this is not a strict wall-clock limit for the whole call. With ``None``, a retriable span failure is left for a later flush rather than retried within this call.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "import posthog\nposthog.capture('event_name', distinct_id='user_id')\n# Before a serverless invocation returns; keep the global client open.\nposthog.flush(timeout_seconds=10)" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "Reads the `evaluation_runtime` each flag definition carries, so no extra request is made. Returns `None` when local evaluation has not loaded a definition for this key. A definition that carries no runtime reports `FeatureFlagEvaluationRuntime.ALL`, the default PostHog applies.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_evaluation_runtime\nruntime = get_feature_flag_evaluation_runtime(\"my-flag\")" - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate.", - "details": "A flag set to `FeatureFlagEvaluationRuntime.ALL` suits either runtime, so it is returned for `CLIENT` and for `SERVER`. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_keys_by_evaluation_runtime\nclient_keys = get_feature_flag_keys_by_evaluation_runtime(FeatureFlagEvaluationRuntime.CLIENT)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and stop the client's background workers. Use `shutdown()` directly in most cases. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Attempt final delivery and permanently shut down the global client. Call this for final process cleanup, not at the end of each request or serverless invocation that shares the module-level client. Use ``flush()`` before returning from those invocations instead. Shutdown closes capture lanes, stops background workers and the feature flag poller, and tears down integrations. The global client is not recreated automatically after shutdown. This normally blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Event draining has no timeout. Queued spans get a final flush with up to 30 seconds waiting for an in-flight flush, then a fresh 30-second drain budget; the last HTTP request is not cut short. Unsent queued spans and still-open spans are discarded with a warning. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. Calls made directly from SDK callbacks such as ``on_error`` are deferred to avoid deadlocking the worker. If blocking completion is required, signal an application-owned thread, return from the callback, and call ``shutdown()`` from that thread. Do not wait inside a callback for another thread or task calling a lifecycle method.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "import posthog\nposthog.traces = {\"service_name\": \"checkout-api\"}\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Tracing", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.86.4.json b/references/posthog-python-references-7.86.4.json deleted file mode 100644 index 587faa0ba..000000000 --- a/references/posthog-python-references-7.86.4.json +++ /dev/null @@ -1,3572 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.86.4", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "Optional[int]", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "Optional[int]", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "float" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "float" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "enable_full_ai_capture", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_trace_context", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "traces", - "description": "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.", - "isOptional": true, - "type": "dict" - }, - { - "name": "app_host", - "description": "Your PostHog app host, such as ``https://posthog.example.com``. ``emails`` sends there. Needed only when ``host`` is not PostHog Cloud, for example a reverse proxy, which must not receive the secret key.", - "isOptional": true, - "type": "str" - }, - { - "name": "email_request_timeout_seconds", - "description": "Timeout in seconds for each email send request. Defaults to 15.", - "isOptional": false, - "type": "float" - }, - { - "name": "email_request_max_retries", - "description": "Number of retries for an email send after a network error, a rate limit, or an unavailable service. Defaults to 2. Set to 0 when a job runner already retries the send.", - "isOptional": false, - "type": "int" - }, - { - "name": "migrated_from", - "description": "The email provider you moved from, such as ``\"resend\"``. ``emails`` sends it with every request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to. Falls back to the context distinct ID; the call is dropped with a warning if neither is available.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is queued on an isolated AI lane with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are omitted from the snapshot and listed with a reason in its ``unresolved_flags``.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is True. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Attempt immediate delivery of queued events, ended spans and autocaptured metrics, keeping the client reusable. For a client shared across requests or serverless invocations (including the module-level client), call ``flush()`` before a short-lived invocation returns. Use ``shutdown()`` instead only for final process cleanup or when disposing of a client that will not be reused. Flush does not stop the background workers or feature flag poller, and does not end open spans. Returning does not guarantee server receipt: pending work can remain after a timeout or span export failure, and failed events may be dropped by the consumers. Calls made directly from SDK callbacks such as ``on_error`` are deferred rather than blocking the worker that invoked the callback.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Seconds to wait for event queues to drain, shared across event lanes. Defaults to 10 seconds. Pass ``None`` to wait without a time limit; this does not guarantee successful delivery. Queued spans flush concurrently. The span exporter waits up to this many seconds for an in-flight flush, then uses a fresh drain budget once it acquires the lock. If the lock wait times out, the in-flight flush is left to finish. At least one span request is attempted after acquiring the lock, even with no budget left; retriable failures are retried after backoff while budget remains, with one last attempt at the deadline. Each span request is bounded by the client's ``timeout`` in seconds, and the last request is not cut short. This is therefore not a strict wall-clock limit for the whole call. With ``None``, a retriable span failure is left for a later flush rather than retried within this call.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name', distinct_id='user_id')\n# Before a serverless invocation returns; keep the shared client open.\nposthog.flush(timeout_seconds=10)" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nruntime = posthog.get_feature_flag_evaluation_runtime(\"my-flag\")\nif runtime is FeatureFlagEvaluationRuntime.SERVER:\n ..." - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate. A flag set to ``FeatureFlagEvaluationRuntime.ALL`` suits either runtime, so it is returned for ``CLIENT`` and for ``SERVER``, and asking for ``ALL`` returns every loaded flag. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "The runtime to match, as a ``FeatureFlagEvaluationRuntime`` or its string value.", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nclient_keys = posthog.get_feature_flag_keys_by_evaluation_runtime(\n FeatureFlagEvaluationRuntime.CLIENT\n)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user, preserving valid serialized JSON.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Optional[str]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team'). Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and end the consumer threads. Do not use directly, call `shutdown()` instead. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Attempt final delivery and permanently shut down the client. Call this for final process cleanup or when disposing of a client that will not be reused. It closes capture lanes, stops background workers and the feature flag poller, and tears down integrations. Do not call it at the end of each request or serverless invocation when the client is shared; call ``flush()`` before returning instead. A shut-down client cannot be reused; create a new client if needed. Normally this method blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Event draining has no timeout. Queued spans get one final flush with up to 30 seconds waiting for an in-flight flush, then a fresh 30-second drain budget; the last HTTP request is not cut short. Any spans it cannot send are discarded with a warning, as are spans still open. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. When called directly from an SDK callback such as ``on_error``, shutdown is deferred to avoid blocking the worker that invoked the callback. If the callback must coordinate a blocking shutdown, have it signal an application-owned thread and return before that thread calls shutdown. Do not wait inside the callback for another thread or task that calls a lifecycle method.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span. A forked child starts with no active span; pass the parent span to continue a trace across a fork.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog = Posthog(\"\", traces={\"service_name\": \"checkout-api\"})\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is delivered on an isolated queue with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name, normally one of the `$ai_*` event names. **kwargs: Same optional arguments as `capture()`.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import capture_ai\n\nuuid = capture_ai(\n \"$ai_generation\",\n distinct_id=\"user_123\",\n properties={\"$ai_model\": \"gpt-5\"},\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip. Overriding reserved exception properties through ``properties`` is deprecated and will stop working in the next major version.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation and omit flags that cannot be evaluated locally. The snapshot's ``unresolved_flags`` lists them with a reason.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is ``True``. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Attempt immediate delivery of queued events and ended spans, keeping the global client reusable. Call ``flush()`` before a short-lived request or serverless invocation returns when using the shared module-level client. Use ``shutdown()`` only for final process cleanup or a client that will not be reused. Flush does not stop the background workers or feature flag poller, and does not end open spans. Returning does not guarantee server receipt: pending work can remain after a timeout or span export failure, and failed events may be dropped by consumers. Calls made directly from SDK callbacks such as ``on_error`` are deferred rather than blocking the worker that invoked the callback.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Seconds to wait for event queues to drain, shared across event lanes. Defaults to 10 seconds. Pass ``None`` to wait without a time limit; this does not guarantee successful delivery. Queued spans flush concurrently, waiting up to this many seconds for an in-flight flush before starting a fresh drain budget. A lock wait timeout leaves the in-flight flush to finish. At least one span request is attempted after acquiring the lock, even with no budget left; retriable failures are retried after backoff while budget remains, with one last attempt at the deadline. The last span request is not cut short and is bounded by the client's ``timeout`` in seconds, so this is not a strict wall-clock limit for the whole call. With ``None``, a retriable span failure is left for a later flush rather than retried within this call.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "import posthog\nposthog.capture('event_name', distinct_id='user_id')\n# Before a serverless invocation returns; keep the global client open.\nposthog.flush(timeout_seconds=10)" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "Reads the `evaluation_runtime` each flag definition carries, so no extra request is made. Returns `None` when local evaluation has not loaded a definition for this key. A definition that carries no runtime reports `FeatureFlagEvaluationRuntime.ALL`, the default PostHog applies.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_evaluation_runtime\nruntime = get_feature_flag_evaluation_runtime(\"my-flag\")" - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate.", - "details": "A flag set to `FeatureFlagEvaluationRuntime.ALL` suits either runtime, so it is returned for `CLIENT` and for `SERVER`. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_keys_by_evaluation_runtime\nclient_keys = get_feature_flag_keys_by_evaluation_runtime(FeatureFlagEvaluationRuntime.CLIENT)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and stop the client's background workers. Use `shutdown()` directly in most cases. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Attempt final delivery and permanently shut down the global client. Call this for final process cleanup, not at the end of each request or serverless invocation that shares the module-level client. Use ``flush()`` before returning from those invocations instead. Shutdown closes capture lanes, stops background workers and the feature flag poller, and tears down integrations. The global client is not recreated automatically after shutdown. This normally blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Event draining has no timeout. Queued spans get a final flush with up to 30 seconds waiting for an in-flight flush, then a fresh 30-second drain budget; the last HTTP request is not cut short. Unsent queued spans and still-open spans are discarded with a warning. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. Calls made directly from SDK callbacks such as ``on_error`` are deferred to avoid deadlocking the worker. If blocking completion is required, signal an application-owned thread, return from the callback, and call ``shutdown()`` from that thread. Do not wait inside a callback for another thread or task calling a lifecycle method.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "import posthog\nposthog.traces = {\"service_name\": \"checkout-api\"}\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Tracing", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file diff --git a/references/posthog-python-references-7.86.5.json b/references/posthog-python-references-7.86.5.json deleted file mode 100644 index 9ad33f5ee..000000000 --- a/references/posthog-python-references-7.86.5.json +++ /dev/null @@ -1,3572 +0,0 @@ -{ - "id": "posthog-python", - "hogRef": "0.3", - "info": { - "version": "7.86.5", - "id": "posthog-python", - "title": "PostHog Python SDK", - "description": "Integrate PostHog into any python application.", - "slugPrefix": "posthog-python", - "specUrl": "https://github.com/PostHog/posthog-python" - }, - "types": [ - { - "id": "FeatureFlag", - "name": "FeatureFlag", - "path": "posthog.types.FeatureFlag", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "reason", - "type": "Optional[FlagReason]", - "description": "Field: reason" - }, - { - "name": "metadata", - "type": "Union[FlagMetadata, LegacyFlagMetadata]", - "description": "Field: metadata" - } - ], - "example": "" - }, - { - "id": "FeatureFlagResult", - "name": "FeatureFlagResult", - "path": "posthog.types.FeatureFlagResult", - "properties": [ - { - "name": "key", - "type": "str", - "description": "Field: key" - }, - { - "name": "enabled", - "type": "bool", - "description": "Field: enabled" - }, - { - "name": "variant", - "type": "Optional[str]", - "description": "Field: variant" - }, - { - "name": "payload", - "type": "Optional[Any]", - "description": "Field: payload" - }, - { - "name": "reason", - "type": "Optional[str]", - "description": "Field: reason" - } - ], - "example": "" - }, - { - "id": "FlagMetadata", - "name": "FlagMetadata", - "path": "posthog.types.FlagMetadata", - "properties": [ - { - "name": "id", - "type": "Optional[int]", - "description": "Field: id" - }, - { - "name": "payload", - "type": "Optional[str]", - "description": "Field: payload" - }, - { - "name": "version", - "type": "Optional[int]", - "description": "Field: version" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - }, - { - "name": "has_experiment", - "type": "Optional[bool]", - "description": "Field: has_experiment" - } - ], - "example": "" - }, - { - "id": "FlagReason", - "name": "FlagReason", - "path": "posthog.types.FlagReason", - "properties": [ - { - "name": "code", - "type": "str", - "description": "Field: code" - }, - { - "name": "condition_index", - "type": "Optional[int]", - "description": "Field: condition_index" - }, - { - "name": "description", - "type": "str", - "description": "Field: description" - } - ], - "example": "" - }, - { - "id": "FlagsAndPayloads", - "name": "FlagsAndPayloads", - "path": "posthog.types.FlagsAndPayloads", - "properties": [ - { - "name": "featureFlags", - "type": "Optional[dict[str, Union[bool, str]]]", - "description": "Field: featureFlags" - }, - { - "name": "featureFlagPayloads", - "type": "Optional[dict[str, Any]]", - "description": "Field: featureFlagPayloads" - } - ], - "example": "" - }, - { - "id": "FlagsResponse", - "name": "FlagsResponse", - "path": "posthog.types.FlagsResponse", - "properties": [ - { - "name": "flags", - "type": "dict[str, FeatureFlag]", - "description": "Field: flags" - }, - { - "name": "errorsWhileComputingFlags", - "type": "bool", - "description": "Field: errorsWhileComputingFlags" - }, - { - "name": "requestId", - "type": "str", - "description": "Field: requestId" - }, - { - "name": "quotaLimit", - "type": "Optional[list[str]]", - "description": "Field: quotaLimit" - }, - { - "name": "evaluatedAt", - "type": "Optional[int]", - "description": "Field: evaluatedAt" - }, - { - "name": "minimalFlagCalledEvents", - "type": "bool", - "description": "Field: minimalFlagCalledEvents" - } - ], - "example": "" - }, - { - "id": "LegacyFlagMetadata", - "name": "LegacyFlagMetadata", - "path": "posthog.types.LegacyFlagMetadata", - "properties": [ - { - "name": "payload", - "type": "Any", - "description": "Field: payload" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - }, - { - "id": "OptionalCaptureArgs", - "name": "OptionalCaptureArgs", - "path": "posthog.args.OptionalCaptureArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "groups", - "type": "NotRequired[Optional[dict[str, str]]]", - "description": "Field: groups" - }, - { - "name": "flags", - "type": "NotRequired[Optional[ForwardRef('FeatureFlagEvaluations')]]", - "description": "Field: flags" - }, - { - "name": "send_feature_flags", - "type": "NotRequired[Union[bool, SendFeatureFlagsOptions, any]]", - "description": "Field: send_feature_flags" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - }, - { - "name": "_property_allowlist", - "type": "NotRequired[Optional[frozenset[str]]]", - "description": "Field: _property_allowlist" - } - ], - "example": "" - }, - { - "id": "OptionalSetArgs", - "name": "OptionalSetArgs", - "path": "posthog.args.OptionalSetArgs", - "properties": [ - { - "name": "distinct_id", - "type": "NotRequired[Union[Number, str, UUID, int, any]]", - "description": "Field: distinct_id" - }, - { - "name": "properties", - "type": "NotRequired[Optional[dict[str, Any]]]", - "description": "Field: properties" - }, - { - "name": "timestamp", - "type": "NotRequired[Union[datetime, str, any]]", - "description": "Field: timestamp" - }, - { - "name": "uuid", - "type": "NotRequired[Union[str, UUID, any]]", - "description": "Field: uuid" - }, - { - "name": "disable_geoip", - "type": "NotRequired[Optional[bool]]", - "description": "Field: disable_geoip" - } - ], - "example": "" - }, - { - "id": "SendFeatureFlagsOptions", - "name": "SendFeatureFlagsOptions", - "path": "posthog.types.SendFeatureFlagsOptions", - "properties": [ - { - "name": "should_send", - "type": "bool", - "description": "Field: should_send" - }, - { - "name": "only_evaluate_locally", - "type": "Optional[bool]", - "description": "Field: only_evaluate_locally" - }, - { - "name": "person_properties", - "type": "Optional[dict[str, Any]]", - "description": "Field: person_properties" - }, - { - "name": "group_properties", - "type": "Optional[dict[str, dict[str, Any]]]", - "description": "Field: group_properties" - }, - { - "name": "flag_keys_filter", - "type": "Optional[list[str]]", - "description": "Field: flag_keys_filter" - } - ], - "example": "" - } - ], - "classes": [ - { - "id": "PostHog", - "title": "PostHog", - "description": "This is the SDK reference for the PostHog Python SDK. You can learn more about example usage in the [Python SDK documentation](/docs/libraries/python). You can also follow [Flask](/docs/libraries/flask) and [Django](/docs/libraries/django) guides to integrate PostHog into your project. For long-running applications, create one client during application startup and reuse it for the lifetime of the process. This keeps background queues predictable and makes shutdown flushing straightforward. Multiple clients are still supported for intentional multi-project or multi-host setups.", - "functions": [ - { - "id": "__init__", - "title": "Client", - "description": "Initialize a new PostHog client instance.", - "details": "", - "category": "Initialization", - "params": [ - { - "name": "project_api_key", - "description": "PostHog project API key/token.", - "isOptional": true, - "type": "str" - }, - { - "name": "host", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "debug", - "description": "Enable verbose SDK logging and re-raise errors from public API methods.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_queue_size", - "description": "Maximum number of events buffered before upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "send", - "description": "If False, queueing succeeds but events are not sent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "on_error", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "flush_at", - "description": "Number of queued events that triggers a batch upload.", - "isOptional": false, - "type": "int" - }, - { - "name": "flush_interval", - "description": "Maximum seconds a background consumer waits before flushing a partial batch.", - "isOptional": false, - "type": "float" - }, - { - "name": "gzip", - "description": "Whether to gzip event upload payloads.", - "isOptional": false, - "type": "bool" - }, - { - "name": "max_retries", - "description": "Number of upload retries. Values below 0 are treated as 0.", - "isOptional": false, - "type": "int" - }, - { - "name": "sync_mode", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "timeout", - "description": "HTTP request timeout in seconds for event uploads.", - "isOptional": false, - "type": "float" - }, - { - "name": "thread", - "description": "Number of background consumer threads.", - "isOptional": false, - "type": "int" - }, - { - "name": "poll_interval", - "description": "Seconds between local feature flag definition refreshes.", - "isOptional": false, - "type": "int" - }, - { - "name": "personal_api_key", - "description": "Deprecated alias for ``secret_key``. Still honored for backwards compatibility; prefer ``secret_key``, which also accepts a Project Secret API Key.", - "isOptional": false, - "type": "any" - }, - { - "name": "disabled", - "description": "If True, disable captures and API requests. Useful in tests.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable server-side GeoIP enrichment. Defaults to True.", - "isOptional": false, - "type": "bool" - }, - { - "name": "is_server", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "historical_migration", - "description": "Mark events as historical migration imports.", - "isOptional": false, - "type": "bool" - }, - { - "name": "feature_flags_request_timeout_seconds", - "description": "Timeout in seconds for feature flag and remote config requests.", - "isOptional": false, - "type": "float" - }, - { - "name": "feature_flags_request_max_retries", - "description": "Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.", - "isOptional": false, - "type": "int" - }, - { - "name": "super_properties", - "description": "Properties merged into every captured event.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_exception_autocapture", - "description": "Automatically capture uncaught exceptions.", - "isOptional": false, - "type": "bool" - }, - { - "name": "log_captured_exceptions", - "description": "Also log exceptions captured by error tracking.", - "isOptional": false, - "type": "bool" - }, - { - "name": "project_root", - "description": "Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.", - "isOptional": false, - "type": "any" - }, - { - "name": "privacy_mode", - "description": "For AI observability, capture usage metadata without prompt inputs or outputs.", - "isOptional": false, - "type": "bool" - }, - { - "name": "before_send", - "description": "Optional callback that can modify or drop events before upload. Return ``None`` to drop an event.", - "isOptional": false, - "type": "any" - }, - { - "name": "flag_fallback_cache_url", - "description": "Optional feature flag fallback cache URL, such as ``memory://local/?ttl=300&size=10000`` or a Redis URL.", - "isOptional": false, - "type": "any" - }, - { - "name": "enable_local_evaluation", - "description": "Whether to poll feature flag definitions for local evaluation when a personal API key is configured.", - "isOptional": false, - "type": "bool" - }, - { - "name": "flag_definition_cache_provider", - "description": "Optional external cache provider for sharing feature flag definitions across workers.", - "isOptional": true, - "type": "FlagDefinitionCacheProvider" - }, - { - "name": "capture_exception_code_variables", - "description": "Capture local variable values on exception stack frames.", - "isOptional": false, - "type": "bool" - }, - { - "name": "code_variables_mask_patterns", - "description": "Variable-name patterns to mask when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_ignore_patterns", - "description": "Variable-name patterns to omit when capturing code variables.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_mask_url_credentials", - "description": "Scrub credentials embedded in URLs/DSNs (e.g. ``user:pass@host``) from captured code variables, regardless of the surrounding variable name. Defaults to True.", - "isOptional": false, - "type": "any" - }, - { - "name": "code_variables_detect_secrets", - "description": "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.", - "isOptional": false, - "type": "any" - }, - { - "name": "in_app_modules", - "description": "Module/package prefixes treated as in-app frames in captured exceptions.", - "isOptional": false, - "type": "UnionType[list[str], any]" - }, - { - "name": "enable_exception_autocapture_rate_limiting", - "description": "Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.", - "isOptional": false, - "type": "bool" - }, - { - "name": "exception_autocapture_bucket_size", - "description": "Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_rate", - "description": "Tokens restored per refill interval for each exception type's bucket.", - "isOptional": false, - "type": "int" - }, - { - "name": "exception_autocapture_refill_interval_seconds", - "description": "Seconds between token refills for autocaptured exception rate limiting.", - "isOptional": false, - "type": "int" - }, - { - "name": "capture_mode", - "description": "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``.", - "isOptional": false, - "type": "CaptureMode" - }, - { - "name": "capture_compression", - "description": "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.", - "isOptional": false, - "type": "CaptureCompression" - }, - { - "name": "secret_key", - "description": "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_...\")", - "isOptional": false, - "type": "any" - }, - { - "name": "metrics", - "description": "", - "isOptional": true, - "type": "dict" - }, - { - "name": "enable_full_ai_capture", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_trace_context", - "description": "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.", - "isOptional": false, - "type": "bool" - }, - { - "name": "_use_ai_lane", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "_enable_multimodal_capture", - "description": "", - "isOptional": false, - "type": "bool" - }, - { - "name": "traces", - "description": "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.", - "isOptional": true, - "type": "dict" - }, - { - "name": "app_host", - "description": "Your PostHog app host, such as ``https://posthog.example.com``. ``emails`` sends there. Needed only when ``host`` is not PostHog Cloud, for example a reverse proxy, which must not receive the secret key.", - "isOptional": true, - "type": "str" - }, - { - "name": "email_request_timeout_seconds", - "description": "Timeout in seconds for each email send request. Defaults to 15.", - "isOptional": false, - "type": "float" - }, - { - "name": "email_request_max_retries", - "description": "Number of retries for an email send after a network error, a rate limit, or an unavailable service. Defaults to 2. Set to 0 when a job runner already retries the send.", - "isOptional": false, - "type": "int" - }, - { - "name": "migrated_from", - "description": "The email provider you moved from, such as ``\"resend\"``. ``emails`` sends it with every request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import Posthog\n\nposthog = Posthog('', host='')" - } - ] - }, - { - "id": "alias", - "title": "alias", - "description": "Create an alias between two distinct IDs.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The previous distinct ID. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The new distinct ID to alias to. Falls back to the context distinct ID; the call is dropped with a warning if neither is available.", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.alias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Captures an event manually. [Learn about capture best practices](https://posthog.com/docs/product-analytics/capture-events)", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "The event name to capture.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Anonymous event", - "code": "# Anonymous event\nposthog.capture('some-anon-event')" - }, - { - "id": "example_2", - "name": "Context usage", - "code": "# Context usage\nfrom posthog import identify_context, new_context\nwith new_context():\n identify_context('distinct_id_of_the_user')\n posthog.capture('user_signed_up')\n posthog.capture('user_logged_in')\n posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')" - }, - { - "id": "example_3", - "name": "Set event properties", - "code": "# Set event properties\nposthog.capture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - }, - { - "id": "example_4", - "name": "Page view event", - "code": "# Page view event\nposthog.capture('$pageview', distinct_id=\"distinct_id_of_the_user\", properties={'$current_url': 'https://example.com'})" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is queued on an isolated AI lane with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Capture", - "params": [ - { - "name": "event", - "description": "", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - } - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture an exception for error tracking. When OpenTelemetry is installed and a valid span is active, its trace and span IDs are added as ``$trace_id`` and ``$span_id`` event properties.", - "details": "", - "category": "Error Tracking", - "params": [ - { - "name": "exception", - "description": "The exception to capture.", - "isOptional": true, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "try:\n # Some code that might fail\n pass\nexcept Exception as e:\n posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to :meth:`capture` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request. Local evaluation is transparent: when the poller resolves a flag, the snapshot's ``$feature_flag_called`` events are tagged ``locally_evaluated=True`` and reason ``\"Evaluated locally\"``.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If True, never fall back to remote evaluation \u2014 flags that can't be evaluated locally are omitted from the snapshot and listed with a reason in its ``unresolved_flags``.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is True. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flags = posthog.evaluate_flags(\n \"user_123\",\n person_properties={\"plan\": \"enterprise\"},\n)\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\nposthog.capture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Check if a feature flag is enabled for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Return feature flag definitions loaded for local evaluation. Returns: The currently loaded feature flag definitions, or ``None`` before local evaluation has loaded definitions.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "flush", - "title": "flush", - "description": "Attempt immediate delivery of queued events, ended spans and autocaptured metrics, keeping the client reusable. For a client shared across requests or serverless invocations (including the module-level client), call ``flush()`` before a short-lived invocation returns. Use ``shutdown()`` instead only for final process cleanup or when disposing of a client that will not be reused. Flush does not stop the background workers or feature flag poller, and does not end open spans. Returning does not guarantee server receipt: pending work can remain after a timeout or span export failure, and failed events may be dropped by the consumers. Calls made directly from SDK callbacks such as ``on_error`` are deferred rather than blocking the worker that invoked the callback.", - "details": "", - "category": null, - "params": [ - { - "name": "timeout_seconds", - "description": "Seconds to wait for event queues to drain, shared across event lanes. Defaults to 10 seconds. Pass ``None`` to wait without a time limit; this does not guarantee successful delivery. Queued spans flush concurrently. The span exporter waits up to this many seconds for an in-flight flush, then uses a fresh drain budget once it acquires the lock. If the lock wait times out, the in-flight flush is left to finish. At least one span request is attempted after acquiring the lock, even with no budget left; retriable failures are retried after backoff while budget remains, with one last attempt at the deadline. Each span request is bounded by the client's ``timeout`` in seconds, and the last request is not cut short. This is therefore not a strict wall-clock limit for the whole call. With ``None``, a retriable span failure is left for a later flush rather than retried within this call.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.capture('event_name', distinct_id='user_id')\n# Before a serverless invocation returns; keep the shared client open.\nposthog.flush(timeout_seconds=10)" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all feature flags for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flags and their payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.get_all_flags_and_payloads('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get multivariate feature flag value for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nruntime = posthog.get_feature_flag_evaluation_runtime(\"my-flag\")\nif runtime is FeatureFlagEvaluationRuntime.SERVER:\n ..." - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate. A flag set to ``FeatureFlagEvaluationRuntime.ALL`` suits either runtime, so it is returned for ``CLIENT`` and for ``SERVER``, and asking for ``ALL`` returns every loaded flag. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "The runtime to match, as a ``FeatureFlagEvaluationRuntime`` or its string value.", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime\n\nclient_keys = posthog.get_feature_flag_keys_by_evaluation_runtime(\n FeatureFlagEvaluationRuntime.CLIENT\n)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload for a feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "The specific flag value to get payload for.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Deprecated. Use get_feature_flag() instead if you need events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')\n\nif is_my_flag_enabled:\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload for a key by evaluating locally or remotely depending on whether local evaluation is enabled and the flag can be locally evaluated. This also captures the `$feature_flag_called` event unless `send_feature_flag_events` is `False`.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to only evaluate locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')\nif flag_result and flag_result.get_value() == 'variant-key':\n # Do something differently for this user\n # Optional: fetch the payload\n matched_flag_payload = flag_result.payload" - } - ] - }, - { - "id": "get_feature_flags_and_payloads", - "title": "get_feature_flags_and_payloads", - "description": "Get feature flags and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "result = posthog.get_feature_flags_and_payloads('')" - } - ] - }, - { - "id": "get_feature_payloads", - "title": "get_feature_payloads", - "description": "Get feature flag payloads for a user, preserving valid serialized JSON.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Optional[str]]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "payloads = posthog.get_feature_payloads('')" - } - ] - }, - { - "id": "get_feature_variants", - "title": "get_feature_variants", - "description": "Get feature flag variants for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Union[bool, str]]" - } - }, - { - "id": "get_flags_decision", - "title": "get_flags_decision", - "description": "Get feature flags decision.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID of the user.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "A dictionary of group information.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "A dictionary of person properties.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "A dictionary of group properties.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this request.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys_to_evaluate", - "description": "A list of specific flag keys to evaluate. If provided, only these flags will be evaluated, improving performance.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "The device ID for this request.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsResponse" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "decision = posthog.get_flags_decision('user123')" - } - ] - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The remote config feature flag key.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context.", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Identify a group and set its properties.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "The type of group (e.g., 'company', 'team'). Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "The unique identifier for the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "A dictionary of properties to set on the group.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "The timestamp of the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "A unique identifier for the event. If provided, it must be a valid UUID string or uuid.UUID instance; invalid values are ignored and replaced with a newly generated UUID.", - "isOptional": false, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP for this event.", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "The distinct ID of the user performing the action.", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.group_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and end the consumer threads. Do not use directly, call `shutdown()` instead. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.join()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flags for local evaluation.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.load_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context for managing shared state. Learn more about [contexts](/docs/libraries/python#contexts).", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "with client.new_context():\n client.identify_context('')\n client.capture('event_name')" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the wrapped function using this client.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to create a fresh context that doesn't inherit from parent.", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to automatically capture exceptions in this context. If omitted, defaults to this client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a person profile.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set with distinct id", - "code": "# Set with distinct id\nposthog.set(distinct_id='user123', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a person profile only if they haven't been set before.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.set_once(distinct_id='user123', properties={'initial_signup_date': '2024-01-01'})" - } - ] - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Attempt final delivery and permanently shut down the client. Call this for final process cleanup or when disposing of a client that will not be reused. It closes capture lanes, stops background workers and the feature flag poller, and tears down integrations. Do not call it at the end of each request or serverless invocation when the client is shared; call ``flush()`` before returning instead. A shut-down client cannot be reused; create a new client if needed. Normally this method blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Event draining has no timeout. Queued spans get one final flush with up to 30 seconds waiting for an in-flight flush, then a fresh 30-second drain budget; the last HTTP request is not cut short. Any spans it cannot send are discarded with a warning, as are spans still open. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. When called directly from an SDK callback such as ``on_error``, shutdown is deferred to avoid blocking the worker that invoked the callback. If the callback must coordinate a blocking shutdown, have it signal an application-owned thread and return before that thread calls shutdown. Do not wait inside the callback for another thread or task that calls a lifecycle method.", - "details": "", - "category": null, - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog.shutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span. A forked child starts with no active span; pass the parent span to continue a trace across a fork.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "posthog = Posthog(\"\", traces={\"service_name\": \"checkout-api\"})\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value.", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - } - } - ] - }, - { - "id": "PostHogModule", - "title": "PostHog Module Functions", - "description": "Global functions available in the PostHog module", - "functions": [ - { - "id": "alias", - "title": "alias", - "description": "Associate user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "details": "To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call. This will allow you to answer questions like \"Which marketing channels leads to users churning after a month?\" or \"What do users do on our website before signing up?\". Particularly useful for associating user behaviour before and after they e.g. register, login, or perform some other identifying action.", - "category": "Identification", - "params": [ - { - "name": "previous_id", - "description": "The unique ID of the user before", - "isOptional": true, - "type": "Number" - }, - { - "name": "distinct_id", - "description": "The current unique id", - "isOptional": true, - "type": "str" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Alias user", - "code": "# Alias user\nfrom posthog import alias\nalias(previous_id='distinct_id', distinct_id='alias_id')" - } - ] - }, - { - "id": "capture", - "title": "capture", - "description": "Capture anything a user does within your system.", - "details": "Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up. A capture call requires an event name to specify the event. We recommend using [verb] [noun], like `movie played` or `movie updated` to easily identify what your events mean later on. Capture takes a number of optional arguments, which are defined by the `OptionalCaptureArgs` type.", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name to specify the event **kwargs: Optional arguments including:", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Context and capture usage", - "code": "# Context and capture usage\nfrom posthog import new_context, identify_context, tag_context, capture\n# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)\nwith new_context():\n # Associate this context with some user, by distinct_id\n identify_context('some user')\n\n # Capture an event, associated with the context-level distinct ID ('some user')\n capture('movie started')\n\n # Capture an event associated with some other user (overriding the context-level distinct ID)\n capture('movie joined', distinct_id='some-other-user')\n\n # Capture an event with some properties\n capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})\n\n # Capture an event with some properties\n capture('purchase', properties={'product_id': '123', 'category': 'romcom'})\n # Capture an event with some associated group\n capture('purchase', groups={'company': 'id:5'})\n\n # Adding a tag to the current context will cause it to appear on all subsequent events\n tag_context('some-tag', 'some-value')\n\n capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict" - }, - { - "id": "example_2", - "name": "Set event properties", - "code": "# Set event properties\nfrom posthog import capture\ncapture(\n \"user_signed_up\",\n distinct_id=\"distinct_id_of_the_user\",\n properties={\n \"login_type\": \"email\",\n \"is_free_trial\": \"true\"\n }\n)" - } - ] - }, - { - "id": "capture_ai", - "title": "capture_ai", - "description": "Capture an AI event on the dedicated AI capture endpoint. Beta: the signature is stable; operational limits (per-event size cap, batching, endpoint) may change without notice. Takes the same arguments and returns the same value as `capture()`: the event UUID, or None when the event was not admitted (disabled client, or dropped by `before_send`). The event is delivered on an isolated queue with its own consumer pool and a higher per-event size cap, posting to the dedicated AI ingestion endpoint. The payload is sent as given \u2014 no redaction or truncation is applied here.", - "details": "", - "category": "Events", - "params": [ - { - "name": "event", - "description": "The event name, normally one of the `$ai_*` event names. **kwargs: Same optional arguments as `capture()`.", - "isOptional": true, - "type": "str" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import capture_ai\n\nuuid = capture_ai(\n \"$ai_generation\",\n distinct_id=\"user_123\",\n properties={\"$ai_model\": \"gpt-5\"},\n)" - } - ] - }, - { - "id": "capture_exception", - "title": "capture_exception", - "description": "Capture exceptions that happen in your code.", - "details": "Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the \"traceback\"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError(\"Some Error\"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.", - "category": "Events", - "params": [ - { - "name": "exception", - "description": "The exception to capture. If not provided, the current exception is captured via `sys.exc_info()` **kwargs: Optional capture arguments including distinct_id, properties, timestamp, uuid, groups, flags, send_feature_flags, and disable_geoip. Overriding reserved exception properties through ``properties`` is deprecated and will stop working in the next major version.", - "isOptional": false, - "type": "BaseException" - }, - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalCaptureArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Capture exception", - "code": "# Capture exception\nfrom posthog import capture_exception\ntry:\n risky_operation()\nexcept Exception as e:\n capture_exception(e)" - } - ] - }, - { - "id": "evaluate_flags", - "title": "evaluate_flags", - "description": "Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / ``.get_flag()`` and pass the same snapshot to ``capture()`` via the ``flags`` option so events carry the exact flag values the code branched on. Prefer this over repeated ``get_feature_flag()`` calls and over ``capture(send_feature_flags=True)`` \u2014 it consolidates flag evaluation into a single ``/flags`` request per incoming request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID. If ``None``, falls back to the context distinct_id. If still unresolvable, returns an empty snapshot.", - "isOptional": false, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "If ``True``, never fall back to remote evaluation and omit flags that cannot be evaluated locally. The snapshot's ``unresolved_flags`` lists them with a reason.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "flag_keys", - "description": "Optional list that scopes local evaluation, the underlying ``/flags`` request, and the returned snapshot. When omitted or ``None``, all flags are evaluated. An empty list returns an empty snapshot without evaluating flags. A requested key absent from loaded local definitions is included in one remote fallback per ``evaluate_flags`` call unless ``only_evaluate_locally`` is ``True``. If the server also does not know the key, it is omitted from the snapshot.", - "isOptional": true, - "type": "list[str]" - }, - { - "name": "device_id", - "description": "Optional device ID override. If not provided, falls back to the context device_id (which may be set via tracing headers). Used by experience-continuity flags to match users across distinct_id changes.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FeatureFlagEvaluations" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import evaluate_flags, capture\nflags = evaluate_flags(\"user_123\", person_properties={\"plan\": \"enterprise\"})\nif flags.is_enabled(\"new-dashboard\"):\n render_new_dashboard()\ncapture(\"page_viewed\", distinct_id=\"user_123\", flags=flags)" - } - ] - }, - { - "id": "feature_enabled", - "title": "feature_enabled", - "description": "Use feature flags to enable or disable features for users.", - "details": "You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[bool]" - }, - "examples": [ - { - "id": "example_1", - "name": "Boolean feature flag", - "code": "# Boolean feature flag\nfrom posthog import feature_enabled, get_feature_flag_payload\nis_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')\nif is_my_flag_enabled:\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "feature_flag_definitions", - "title": "feature_flag_definitions", - "description": "Returns loaded feature flags.", - "details": "Returns loaded feature flags, if any. Helpful for debugging what flag information you have loaded.", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import feature_flag_definitions\ndefinitions = feature_flag_definitions()" - } - ] - }, - { - "id": "flush", - "title": "flush", - "description": "Attempt immediate delivery of queued events and ended spans, keeping the global client reusable. Call ``flush()`` before a short-lived request or serverless invocation returns when using the shared module-level client. Use ``shutdown()`` only for final process cleanup or a client that will not be reused. Flush does not stop the background workers or feature flag poller, and does not end open spans. Returning does not guarantee server receipt: pending work can remain after a timeout or span export failure, and failed events may be dropped by consumers. Calls made directly from SDK callbacks such as ``on_error`` are deferred rather than blocking the worker that invoked the callback.", - "details": "", - "category": "Client management", - "params": [ - { - "name": "timeout_seconds", - "description": "Seconds to wait for event queues to drain, shared across event lanes. Defaults to 10 seconds. Pass ``None`` to wait without a time limit; this does not guarantee successful delivery. Queued spans flush concurrently, waiting up to this many seconds for an in-flight flush before starting a fresh drain budget. A lock wait timeout leaves the in-flight flush to finish. At least one span request is attempted after acquiring the lock, even with no budget left; retriable failures are retried after backoff while budget remains, with one last attempt at the deadline. The last span request is not cut short and is bounded by the client's ``timeout`` in seconds, so this is not a strict wall-clock limit for the whole call. With ``None``, a retriable span failure is left for a later flush rather than retried within this call.", - "isOptional": true, - "type": "float" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "import posthog\nposthog.capture('event_name', distinct_id='user_id')\n# Before a serverless invocation returns; keep the global client open.\nposthog.flush(timeout_seconds=10)" - } - ] - }, - { - "id": "get_active_span", - "title": "get_active_span", - "description": "The span that is active in the current context, or ``None``. Alpha. Only entering a span (``with posthog.start_span(...) as span:``) makes it active; a span started manually is not. Use it to propagate the trace to the next service: ``span.traceparent()`` is the header value.", - "details": "", - "category": "Tracing", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[Span]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "span = posthog.get_active_span()\nif span is not None:\n headers[\"traceparent\"] = span.traceparent()" - } - ] - }, - { - "id": "get_all_flags", - "title": "get_all_flags", - "description": "Get all flags for a given user.", - "details": "Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate (evaluates all if None)", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[dict[str, Union[bool, str]]]" - }, - "examples": [ - { - "id": "example_1", - "name": "All flags for user", - "code": "# All flags for user\nfrom posthog import get_all_flags\nget_all_flags('distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_all_flags_and_payloads", - "title": "get_all_flags_and_payloads", - "description": "Get all feature flag values and payloads for a user.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - }, - { - "name": "flag_keys_to_evaluate", - "description": "Optional list of flag keys to evaluate. Evaluates all flags when omitted.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "FlagsAndPayloads" - } - }, - { - "id": "get_feature_flag", - "title": "get_feature_flag", - "description": "Get feature flag variant for users. Used with experiments.", - "details": "`groups` are a mapping from group type to group key. So, if you have a group type of \"organization\" and a group key of \"5\", you would pass groups={\"organization\": \"5\"}. `group_properties` take the format: { group_type_name: { group_properties } }. So, for example, if you have the group type \"organization\" and the group key \"5\", with the properties name, and employee count, you'll send these as: group_properties={\"organization\": {\"name\": \"PostHog\", \"employees\": 11}}.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Groups mapping from group type to group key", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties in format { group_type_name: { group_properties } }", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send feature flag events", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Union[bool, str, any]" - }, - "examples": [ - { - "id": "example_1", - "name": "Multivariate feature flag", - "code": "# Multivariate feature flag\nfrom posthog import get_feature_flag, get_feature_flag_payload\nenabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')\nif enabled_variant == 'variant-key':\n matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')" - } - ] - }, - { - "id": "get_feature_flag_evaluation_runtime", - "title": "get_feature_flag_evaluation_runtime", - "description": "Return where a locally loaded feature flag is meant to be evaluated.", - "details": "Reads the `evaluation_runtime` each flag definition carries, so no extra request is made. Returns `None` when local evaluation has not loaded a definition for this key. A definition that carries no runtime reports `FeatureFlagEvaluationRuntime.ALL`, the default PostHog applies.", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagEvaluationRuntime]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_evaluation_runtime\nruntime = get_feature_flag_evaluation_runtime(\"my-flag\")" - } - ] - }, - { - "id": "get_feature_flag_keys_by_evaluation_runtime", - "title": "get_feature_flag_keys_by_evaluation_runtime", - "description": "Return the keys of locally loaded flags that a runtime can evaluate.", - "details": "A flag set to `FeatureFlagEvaluationRuntime.ALL` suits either runtime, so it is returned for `CLIENT` and for `SERVER`. Use this to decide which flags to hand to a browser when a backend serves flags to its own frontend.", - "category": "Feature flags", - "params": [ - { - "name": "evaluation_runtime", - "description": "", - "isOptional": true, - "type": "FeatureFlagEvaluationRuntime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "list[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import FeatureFlagEvaluationRuntime, get_feature_flag_keys_by_evaluation_runtime\nclient_keys = get_feature_flag_keys_by_evaluation_runtime(FeatureFlagEvaluationRuntime.CLIENT)" - } - ] - }, - { - "id": "get_feature_flag_payload", - "title": "get_feature_flag_payload", - "description": "Get the payload associated with a feature flag value. Deprecated for new code. Prefer ``evaluate_flags()`` and ``flags.get_flag_payload(key)`` so flag evaluation happens once per request.", - "details": "", - "category": "Feature flags", - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "match_value", - "description": "Optional flag value to use when selecting a payload.", - "isOptional": false, - "type": "bool" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[object]" - } - }, - { - "id": "get_feature_flag_result", - "title": "get_feature_flag_result", - "description": "Get a FeatureFlagResult object which contains the flag result and payload. This method evaluates a feature flag and returns a FeatureFlagResult object containing: - enabled: Whether the flag is enabled - variant: The variant value if the flag has variants - payload: The payload associated with the flag (automatically deserialized from JSON) - key: The flag key - reason: Why the flag was enabled/disabled", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The feature flag key.", - "isOptional": true, - "type": "str" - }, - { - "name": "distinct_id", - "description": "The user's distinct ID.", - "isOptional": true, - "type": "Number" - }, - { - "name": "groups", - "description": "Mapping of group type to group key.", - "isOptional": true, - "type": "Mapping[str, Union[str, int]]" - }, - { - "name": "person_properties", - "description": "Person properties to use for evaluation.", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "group_properties", - "description": "Group properties keyed by group type.", - "isOptional": true, - "type": "dict[str, dict[str, Any]]" - }, - { - "name": "only_evaluate_locally", - "description": "Whether to evaluate only locally.", - "isOptional": false, - "type": "bool" - }, - { - "name": "send_feature_flag_events", - "description": "Whether to send a $feature_flag_called event.", - "isOptional": false, - "type": "bool" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup.", - "isOptional": true, - "type": "bool" - }, - { - "name": "device_id", - "description": "Optional device ID override for experience-continuity flags.", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[FeatureFlagResult]" - } - }, - { - "id": "get_remote_config_payload", - "title": "get_remote_config_payload", - "description": "Get the payload for a remote config feature flag.", - "details": "", - "category": null, - "params": [ - { - "name": "key", - "description": "The key of the feature flag", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "get_tags", - "title": "get_tags", - "description": "Get all tags from the current context. Returns: Dict of all tags in the current context", - "details": "", - "category": "Contexts", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "dict[str, Any]" - } - }, - { - "id": "group_identify", - "title": "group_identify", - "description": "Set properties on a group.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "group_type", - "description": "Type of your group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "group_key", - "description": "Unique identifier of the group. Required - the call is dropped with a warning if it is missing or empty.", - "isOptional": true, - "type": "str" - }, - { - "name": "properties", - "description": "Properties to set on the group", - "isOptional": true, - "type": "dict[str, Any]" - }, - { - "name": "timestamp", - "description": "Optional timestamp for the event. UTC is preferred; non-UTC datetimes and parseable ISO timestamp strings are converted to UTC.", - "isOptional": false, - "type": "datetime" - }, - { - "name": "uuid", - "description": "Optional UUID for the event", - "isOptional": true, - "type": "str" - }, - { - "name": "disable_geoip", - "description": "Whether to disable GeoIP lookup", - "isOptional": true, - "type": "bool" - }, - { - "name": "distinct_id", - "description": "Optional distinct ID of the user performing the action", - "isOptional": false, - "type": "Number" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Group identify", - "code": "# Group identify\nfrom posthog import group_identify\ngroup_identify('company', 'company_id_in_your_db', {\n 'name': 'Awesome Inc.',\n 'employees': 11\n})" - } - ] - }, - { - "id": "identify_context", - "title": "identify_context", - "description": "Identify the current context with a distinct ID.", - "details": "", - "category": "Identification", - "params": [ - { - "name": "distinct_id", - "description": "The distinct ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import identify_context\nidentify_context(\"user_123\")" - } - ] - }, - { - "id": "join", - "title": "join", - "description": "Attempt to process queued events and stop the client's background workers. Use `shutdown()` directly in most cases. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import join\njoin()" - } - ] - }, - { - "id": "load_feature_flags", - "title": "load_feature_flags", - "description": "Load feature flag definitions from PostHog.", - "details": "", - "category": "Feature flags", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import load_feature_flags\nload_feature_flags()" - } - ] - }, - { - "id": "new_context", - "title": "new_context", - "description": "Create a new context scope that will be active for the duration of the with block.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture exceptions raised within the context. If omitted, defaults to the relevant client's exception autocapture setting.", - "isOptional": true, - "type": "bool" - }, - { - "name": "client", - "description": "Optional Posthog client instance to use for this context (default: None)", - "isOptional": true, - "type": "Client" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import new_context, tag, capture\nwith new_context():\n tag(\"request_id\", \"123\")\n capture(\"event_name\", properties={\"property\": \"value\"})" - } - ] - }, - { - "id": "scoped", - "title": "scoped", - "description": "Decorator that creates a new context for the function.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "fresh", - "description": "Whether to start with a fresh context (default: False)", - "isOptional": false, - "type": "bool" - }, - { - "name": "capture_exceptions", - "description": "Whether to capture and track exceptions with posthog error tracking. If omitted, defaults to the global exception autocapture setting.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import scoped, tag, capture\n@scoped()\ndef process_payment(payment_id):\n tag(\"payment_id\", payment_id)\n capture(\"payment_started\")" - } - ] - }, - { - "id": "set", - "title": "set", - "description": "Set properties on a user record.", - "details": "This will overwrite previous people property values. Generally operates similar to `capture`, with distinct_id being an optional argument, defaulting to the current context's distinct ID. If there is no context-level distinct ID, and no override distinct_id is passed, this function will do nothing. Context tags are folded into $set properties, so tagging the current context and then calling `set` will cause those tags to be set on the user (unlike capture, which causes them to just be set on the event).", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set person properties", - "code": "# Set person properties\nfrom posthog import set\nset(distinct_id='distinct_id', properties={'name': 'Max Hedgehog'})" - } - ] - }, - { - "id": "set_capture_exception_code_variables_context", - "title": "set_capture_exception_code_variables_context", - "description": "Override code-variable capture for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "Whether exceptions captured in this context should include local variable values from stack frames.", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_detect_secrets_context", - "title": "set_code_variables_detect_secrets_context", - "description": "Whether to apply entropy-based secret detection as a last-resort redaction of high-entropy values (API keys, tokens, strong passwords) in captured code variables for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_ignore_patterns_context", - "title": "set_code_variables_ignore_patterns_context", - "description": "Override code-variable ignore patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "ignore_patterns", - "description": "Variable-name patterns that should be omitted entirely when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_patterns_context", - "title": "set_code_variables_mask_patterns_context", - "description": "Override code-variable mask patterns for exceptions in the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "mask_patterns", - "description": "Variable-name patterns whose values should be replaced with ``***`` when code variables are captured.", - "isOptional": true, - "type": "list[str]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_code_variables_mask_url_credentials_context", - "title": "set_code_variables_mask_url_credentials_context", - "description": "Whether to scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables for the current context.", - "details": "", - "category": null, - "params": [ - { - "name": "enabled", - "description": "", - "isOptional": true, - "type": "bool" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - } - }, - { - "id": "set_context_device_id", - "title": "set_context_device_id", - "description": "Set the device ID for the current context, associating all feature flag requests in this or child contexts with the given device ID.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "device_id", - "description": "The device ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_device_id\nset_context_device_id(\"device_123\")" - } - ] - }, - { - "id": "set_context_session", - "title": "set_context_session", - "description": "Set the session ID for the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "session_id", - "description": "The session ID to associate with the current context and its children", - "isOptional": true, - "type": "str" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import set_context_session\nset_context_session(\"session_123\")" - } - ] - }, - { - "id": "set_once", - "title": "set_once", - "description": "Set properties on a user record, only if they do not yet exist.", - "details": "This will not overwrite previous people property values, unlike `set`. Otherwise, operates in an identical manner to `set`.", - "category": "Identification", - "params": [ - { - "name": "kwargs", - "description": "", - "isOptional": true, - "type": "Unpack[OptionalSetArgs]" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Optional[str]" - }, - "examples": [ - { - "id": "example_1", - "name": "Set property once", - "code": "# Set property once\nfrom posthog import set_once\nset_once(distinct_id='distinct_id', properties={'initial_url': '/blog'})" - } - ] - }, - { - "id": "setup", - "title": "setup", - "description": "Create or return the global PostHog client configured by module settings. Most applications should either instantiate ``Posthog`` directly or set ``posthog.api_key``/other module settings before calling top-level helpers. ``setup()`` is called automatically by global APIs such as ``capture()``. Returns: The global ``Client`` instance. If both ``api_key`` and ``project_api_key`` are missing or blank, the client is disabled and module-level calls become no-ops.", - "details": "", - "category": "Initialization", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Client" - } - }, - { - "id": "shutdown", - "title": "shutdown", - "description": "Attempt final delivery and permanently shut down the global client. Call this for final process cleanup, not at the end of each request or serverless invocation that shares the module-level client. Use ``flush()`` before returning from those invocations instead. Shutdown closes capture lanes, stops background workers and the feature flag poller, and tears down integrations. The global client is not recreated automatically after shutdown. This normally blocks until queued events have been attempted and cleanup finishes. Failed or undrainable events may be dropped and reported through logging or ``on_error``; returning does not guarantee server receipt. Event draining has no timeout. Queued spans get a final flush with up to 30 seconds waiting for an in-flight flush, then a fresh 30-second drain budget; the last HTTP request is not cut short. Unsent queued spans and still-open spans are discarded with a warning. Lifecycle cleanup is attempted once, and cleanup failures are logged without retry. Calls made directly from SDK callbacks such as ``on_error`` are deferred to avoid deadlocking the worker. If blocking completion is required, signal an application-owned thread, return from the callback, and call ``shutdown()`` from that thread. Do not wait inside a callback for another thread or task calling a lifecycle method.", - "details": "", - "category": "Client management", - "params": [], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "any" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import shutdown\nshutdown()" - } - ] - }, - { - "id": "start_span", - "title": "start_span", - "description": "Start a span for distributed tracing. Alpha. Returns a span handle. Use it as a context manager to make it the active span for the block and end it on exit (recording a raised exception on the way out); or call ``end()`` yourself for a span that cannot wrap a block. Spans started inside the block nest under it automatically. Always returns a usable handle, even when tracing is off, so calling code never branches.", - "details": "", - "category": "Tracing", - "params": [ - { - "name": "name", - "description": "A low-cardinality operation name, e.g. ``GET /users/:id``. Variable values belong in attributes, not the name.", - "isOptional": true, - "type": "str" - }, - { - "name": "kind", - "description": "``internal`` (default), ``server``, ``client``, ``producer`` or ``consumer``.", - "isOptional": true, - "type": "str" - }, - { - "name": "attributes", - "description": "Initial attributes.", - "isOptional": true, - "type": "Mapping[str, Any]" - }, - { - "name": "parent", - "description": "A span handle, or an inbound W3C ``traceparent`` header value to continue a remote trace. Defaults to the active span.", - "isOptional": false, - "type": "Span" - }, - { - "name": "tracestate", - "description": "The inbound ``tracestate`` header accompanying a ``traceparent`` string ``parent``; preserved and propagated.", - "isOptional": true, - "type": "str" - }, - { - "name": "start_time", - "description": "A ``datetime`` or epoch seconds, to backdate the span.", - "isOptional": false, - "type": "datetime" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "Span" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "import posthog\nposthog.traces = {\"service_name\": \"checkout-api\"}\n\nwith posthog.start_span(\"POST /checkout\", parent=request.headers.get(\"traceparent\")) as span:\n span.set_attribute(\"plan\", user.plan)\n with posthog.start_span(\"db.query\", kind=\"client\"):\n ...\n outgoing_headers = {\"traceparent\": span.traceparent()}" - } - ] - }, - { - "id": "tag", - "title": "tag", - "description": "Add a tag to the current context.", - "details": "", - "category": "Contexts", - "params": [ - { - "name": "name", - "description": "The tag key", - "isOptional": true, - "type": "str" - }, - { - "name": "value", - "description": "The tag value", - "isOptional": true, - "type": "Any" - } - ], - "showDocs": true, - "releaseTag": "public", - "returnType": { - "id": "return_type", - "name": "None" - }, - "examples": [ - { - "id": "example_1", - "name": "Example 1", - "code": "from posthog import tag\ntag(\"user_id\", \"123\")" - } - ] - } - ] - } - ], - "categories": [ - "Initialization", - "Identification", - "Capture", - "Error Tracking", - "Feature flags", - "Tracing", - "Contexts", - "Events", - "Client management" - ] -} \ No newline at end of file